GDB-ADD-INDEX(1)

📦 version 17.2, in arch rolling

💅 gdb-add-index — bestie edition

okay so this is gdb-add-index from the GNU Development Tools manual suite, section 1 of the man pages, and it's genuinely one of the most underrated little glow-ups in the whole debugging world. sit down, we're building an index. 🎀

✨ NAME ✨

gdb-add-index — adds index files to your binary so GDB starts up fast. no cap.

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

so here's the tea: when GDB finds a symbol file, it scans all the symbols in that file to build up an internal symbol table. and like — that's a good thing, because it makes most GDB operations run super quickly. slay. but the tradeoff is a delay at the very beginning. and for large programs? bestie, that delay can be quite lengthy. 😭

so GDB gives you a way to build an index ahead of time, which speeds up startup. main character energy, honestly.

to check whether a file already has such an index, use readelf -S filename — the index lives in a section named .gdb_index (pre-DWARF 5) or .debug_names and .debug_str (DWARF 5). and heads up: indexes can only be produced on systems that use ELF binaries and DWARF debug information — meaning sections named .debug_*. that's the vibe check, sorry. 💀

by default gdb-add-index will add a pre-DWARF 5 .gdb_index section to filename. with --dwarf-5, the DWARF 5 section .debug_names is added instead. choose your fighter. ✨

filename must be writable. no writable, no index. periodt.

gdb-add-index uses GDB, objcopy, and readelf found in the PATH environment variable. if you wanna use different versions of these programs — totally valid — you can specify them through the appropriate environment variables (see below, i got you 🫶).

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.

see more in the GDB manual in 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. the modern choice, lowkey.
  • --help, -h — lists all the options with brief explanations. the little tour.
  • --version, -v — prints version information and then exits. bye bestie 👋

🧚 ENVIRONMENT 🧚

  • GDB — full file name of the gdb program to use for index generation. if it's not set, the PATH will be 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 will be 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 will be 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, the command

info gdb

should give you access to the complete manual. iconic.

also on the shelf: Using GDB: A Guide to the GNU Source-Level Debugger, by Richard M. Stallman and Roland H. Pesch, July 1991. vintage but still ate. 👑

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

🌈 okay that's the whole thing!! go forth and index. this page you just read is from gdb-17.2, dated 2026-05-10 — mwah, sending you the biggest hug, now go debug something cute. 💖🦋

📦 where this page comes from