GDB-ADD-INDEX(1)

📦
version 17.2 · 5 versions
, in ubuntu stonking

✨ NAME ✨

gdb-add-index — bestie's lil shortcut for adding index files so GDB starts up actually fast 💖 (this one lives in the GNU Development Tools manual, mwah)

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

okay so picture this: GDB finds a symbol file, and the very first thing it does is scan through every symbol in there to build itself an internal symbol table. that's what makes most GDB operations speedy later — but the trade-off is a delay right at the start. and for big programs? that delay is not a vibe. it's long long. so GDB gives you a way to pre-build an index, which speeds up startup. iconic behaviour honestly 👑

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

by default gdb-add-index will drop a pre-DWARF 5 .gdb_index section into filename. but if you pass --dwarf-5, you get the DWARF 5 section .debug_names added instead. pick your fighter 💅

filename must be writable. like, that's non-negotiable.

gdb-add-index uses the GDB, objcopy, and readelf it finds via the PATH environment variable. and if you wanna use different versions of those programs, you can specify them through the appropriate environment variables (scroll down, they're in their own section 🫶).

as for how it goes: gdb-add-index exits with status 0 if it succeeds in creating the index for filename, or greater than 0 if an error occurs. simple as.

and there's more lore in the GDB manual, in the node "Index Files" — hit up this shell command:

info -f gdb -n "Index Files"

🎀 OPTIONS 🎀

  • --dwarf-5 — adds DWARF 5 sections instead of that previous .gdb_index section. glow up ✨
  • --help, -h — lists all the options, with brief explanations. your lil menu, bestie 🍓
  • --version, -v — prints version information and then peaces out (exits).

🌈 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 a 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 all properly installed at your site, this command:

info gdb

should give you access to the complete manual. go off 💅

also, Using GDB: A Guide to the GNU Source-Level Debugger, by Richard M. Stallman and Roland H. Pesch, July 1991. vintage but make it iconic 📚

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

ok that's the whole page, no cap. this was gdb-17.2, dated 2026-05-17, and it's page GDB-ADD-INDEX(1) of the GNU Development Tools manual. go build that index bestie, mwah 💖🦋✨
📦 where this page comes from