Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gdb-add-index.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "GDB-ADD-INDEX 1"
61 .TH GDB-ADD-INDEX 1 2026-04-21 gdb-16.3 "GNU Development Tools"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 gdb\-add\-index \- Add index files to speed up GDB
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 gdb\-add\-index [\-dwarf\-5] \fIfilename\fR
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 When GDB finds a symbol file, it scans the symbols in the
74 file in order to construct an internal symbol table. This lets most
75 GDB operations work quickly\-\-at the cost of a delay early on.
76 For large programs, this delay can be quite lengthy, so GDB
77 provides a way to build an index, which speeds up startup.
78 .PP
79 To determine whether a file contains such an index, use the command
80 \&\f(CW\*(C`readelf \-S filename\*(C'\fR: the index is stored in a section named
81 \&\f(CW\*(C`.gdb_index\*(C'\fR (pre\-DWARF 5) or \f(CW\*(C`.debug_names\*(C'\fR and
82 \&\f(CW\*(C`.debug_str\*(C'\fR (DWARF 5). Indexes can only be produced on systems
83 which use ELF binaries and DWARF debug information (i.e., sections
84 named \f(CW\*(C`.debug_*\*(C'\fR).
85 .PP
86 By default \fBgdb\-add\-index\fR will add a pre\-DWARF 5
87 \&\f(CW\*(C`.gdb_index\*(C'\fR section to \fIfilename\fR. With \fB\-dwarf\-5\fR
88 DWARF 5 sections are added instead.
89 .PP
90 \&\fIfilename\fR must be writable.
91 .PP
92 \&\fBgdb\-add\-index\fR uses GDB, \fBobjcopy\fR, and
93 \&\fBreadelf\fR found in the \fBPATH\fR environment variable. If
94 you want to use different versions of these programs, you can specify
95 them through the appropriate environment variables (see below).
96 .PP
97 \&\fBgdb\-add\-index\fR exits with status 0 if it succeeds in creating
98 the index for \fIfilename\fR or greater than 0 if an error occurs.
99 .PP
100 See more in
101 the GDB manual in node \f(CW\*(C`Index Files\*(C'\fR
102 \&\-\- shell command \f(CW\*(C`info \-f gdb \-n "Index Files"\*(C'\fR.
103 .SH OPTIONS
104 .IX Header "OPTIONS"
105 .IP \fB\-dwarf\-5\fR 4
106 .IX Item "-dwarf-5"
107 Add DWARF 5 sections instead of previous \f(CW\*(C`.debug_index\*(C'\fR section.
108 .SH ENVIRONMENT
109 .IX Header "ENVIRONMENT"
110 .IP \fBGDB\fR 4
111 .IX Item "GDB"
112 Full file name of the \f(CW\*(C`gdb\*(C'\fR program to use for index generation.
113 If not set, the \fBPATH\fR will be searched for a \f(CW\*(C`gdb\*(C'\fR program.
114 .IP \fBOBJCOPY\fR 4
115 .IX Item "OBJCOPY"
116 Full file name of the \f(CW\*(C`objcopy\*(C'\fR program to use to copy section
117 information into the given file. If not set, the \fBPATH\fR will be searched
118 for a \f(CW\*(C`objcopy\*(C'\fR program.
119 .IP \fBREADELF\fR 4
120 .IX Item "READELF"
121 Full file name of the \f(CW\*(C`readelf\*(C'\fR program to use to inspect
122 properties of the given file. If not set, the \fBPATH\fR will be searched
123 for a \f(CW\*(C`readelf\*(C'\fR program.
124 .SH "SEE ALSO"
125 .IX Header "SEE ALSO"
126 The full documentation for GDB is maintained as a Texinfo manual.
127 If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB\*(Aqs Texinfo
128 documentation are properly installed at your site, the command
129 .PP
130 .Vb 1
131 \& info gdb
132 .Ve
133 .PP
134 should give you access to the complete manual.
135 .PP
136 \&\fIUsing GDB: A Guide to the GNU Source\-Level Debugger\fR,
137 Richard M. Stallman and Roland H. Pesch, July 1991.
138 .SH COPYRIGHT
139 .IX Header "COPYRIGHT"
140 Copyright (c) 1988\-2024 Free Software Foundation, Inc.
141 .PP
142 Permission is granted to copy, distribute and/or modify this document
143 under the terms of the GNU Free Documentation License, Version 1.3 or
144 any later version published by the Free Software Foundation; with the
145 Invariant Sections being "Free Software" and "Free Software Needs
146 Free Documentation", with the Front\-Cover Texts being "A GNU Manual,"
147 and with the Back\-Cover Texts as in (a) below.
148 .PP
149 (a) The FSF\*(Aqs Back\-Cover Text is: "You are free to copy and modify
150 this GNU Manual. Buying copies from GNU Press supports the FSF in
151 developing GNU and promoting software freedom."