GDB-ADD-INDEX(1)

📦 version 17.1, in arch rolling

✨ NAME ✨

gdb-add-index — it slaps an index file onto your binary so GDB stops making you wait forever 💅

(this is page GDB-ADD-INDEX(1) from the GNU Development Tools manual, bestie — buckle up 🎀)

🌸 SYNOPSIS 🌸

gdb-add-index [-h | --help] [-v | --version] [--dwarf-5] filename

🦋 DESCRIPTION 🦋

okay so picture this: GDB finds a symbol file and then it has to scan all the symbols in it to build its own internal symbol table. that's the whole vibe — it makes most GDB operations go fast, but you pay for it with a little delay at the start 😭 and for big programs? that "little delay" is literally forever. so GDB gives you a way to build an index, which speeds up startup. iconic behavior honestly 👑

to figure out whether a file already has one of these indexes, run readelf -S filename. the index lives in a section called .gdb_index (pre-DWARF 5) or in .debug_names and .debug_str (DWARF 5). heads up tho — indexes can only be produced on systems that use ELF binaries and DWARF debug info (i.e., sections named .debug_*). no ELF, no DWARF, no index, sorry bb 🙈

by default, gdb-add-index adds a pre-DWARF 5 .gdb_index section to filename. but if you pass --dwarf-5, the DWARF 5 section .debug_names gets added instead ✨

ifilename* must be writable. like, actually. it needs to write to it. 🫶

gdb-add-index uses the GDB, objcopy, and readelf that it finds in the PATH environment variable. want different versions of those programs? cool, you can point at them with the appropriate environment variables (scroll down, they're right there 👇).

exit status tea ☕: gdb-add-index exits with status 0 if it successfully creates the index for filename, or greater than 0 if an error happens. that's it, that's the whole vibe check.

want more? there's more in the GDB manual, node Index Files — shell command:

info -f gdb -n "Index Files"

💖 OPTIONS 💖

  • --dwarf-5 — adds DWARF 5 sections instead of the previous .gdb_index section. glow-up for your debug info ✨
  • --help, -h — lists all the options with brief explanations. the "what does anything even do" button 🎀
  • --version, -v — prints version information and then exits. says hi and dips immediately 💅

🌈 ENVIRONMENT 🌈

  • GDB — full file name of the gdb program to use for index generation. if it's not set, the PATH gets searched for a gdb program 🔍
  • OBJCOPY — full file name of the objcopy program, used to copy section information into the given file. if it's not set, the PATH gets searched for an objcopy program 🧚
  • READELF — full file name of the readelf program, used to inspect properties of the given file. if it's not set, the PATH gets searched for a readelf program ⭐

👑 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, this command:

info gdb

should give you access to the complete manual. no cap, that's the whole manual in there 🫶

also, Using GDB: A Guide to the GNU Source-Level Debugger, Richard M. Stallman and Roland H. Pesch, July 1991. a classic. we stan a legacy doc 💜

Copyright (c) 1988-2025 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."

and that's the whole page, bestie! this version is gdb-17.1, dated 2025-12-20 — go forth and index responsibly 🦋💖✨

📦 where this page comes from