GDB-ADD-INDEX(1)

💅 GDB-ADD-INDEX(1) — ok so this is from the GNU Development Tools fam, and bestie, it's a glow-up for your debug symbols

---

✨ NAME ✨

gdb-add-index — literally just adds index files so GDB stops being slow, no cap 🏃‍♀️💨

---

🎀 SYNOPSIS 🎀

gdb-add-index [-dwarf-5] filename

Like, that's it. That's the whole vibe.

---

🌸 DESCRIPTION 🌸

okay so picture this: GDB finds a symbol file, right? And it has to scan all the symbols in that file to build itself an internal symbol table. Which honestly? Iconic of it. It means most GDB operations run super fast — but the tradeoff is a little delay at the start, like waiting for your iced coffee. 🧊

And for big programs? That delay can be quite lengthy. Like, "should I go touch grass while this loads" lengthy. So GDB provides a way to build an index, which speeds up startup. Main character energy tbh 👑

Wanna know whether a file already has such an index? Use the command "readelf -S filename" — the index lives in a section named .gdb_index (pre-DWARF 5) or .debug_names and .debug_str (DWARF 5). 🔍

Heads up bestie: indexes can only be produced on systems which use ELF binaries and DWARF debug information (i.e., sections named .debug_*). No ELF, no DWARF, no index. Sorry. 😭

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. Pick your fighter 💅

filename must be writable. Fr fr, it will not work otherwise 🙈

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 👇). It's giving "customize your squad."

gdb-add-index exits with status 0 if it succeeds in creating the index for filename, or greater than 0 if an error occurs. Zero = slay, nonzero = something went sideways 💀

See more in the GDB manual in node "Index Files" — shell command "info -f gdb -n "Index Files"".

---

⭐ OPTIONS ⭐

• -dwarf-5 — Add DWARF 5 sections instead of the previous .debug_index section. Modern problems require modern sections, yk? ✨

---

🦋 ENVIRONMENT 🦋

• 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. Like, it'll go find one itself, independent queen 🫶
• 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.

(iykyk — set these when you've got multiple toolchain versions lying around and you need exactly the right one 💜)

---

🌈 SEE ALSO 🌈

The full documentation for GDB is maintained as a Texinfo manual. If the "info" and "gdb" programs and GDB's Texinfo documentation are properly installed at your site, the command

info gdb

should give you access to the complete manual. Go off, Texinfo 📚

Using GDB: A Guide to the GNU Source-Level Debugger, Richard M. Stallman and Roland H. Pesch, July 1991. Throwback royalty right there 👑

---

👑 COPYRIGHT 👑

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."

---

🍓 ok bye bestie — this page came to you courtesy of gdb-16.3.90.20250906-git, dated 2026-10-03, and it's a GDB-ADD-INDEX(1) situation. go make those indexes, you're doing amazing 💖