Debugging with GDB: Initialization Files

Previous: Startup, Up: Invoking GDB [Contents][Index]

#### 2.1.4 Initialization Files

During startup (see Startup) GDB will execute commands from several initialization files. These initialization files use the same syntax as command files (see Command Files) and are processed by GDB in the same way.

To display the list of initialization files loaded by GDB at startup, in the order they will be loaded, you can use `gdb --help`.

The early initialization file is loaded very early in GDB’s initialization process, before the interpreter (see Interpreters) has been initialized, and before the default target (see Targets) is initialized. Only `set` or `source` commands should be placed into an early initialization file, and the only `set` commands that can be used are those that control how GDB starts up.

Commands that can be placed into an early initialization file will be documented as such throughout this manual. Any command that is not documented as being suitable for an early initialization file should instead be placed into a general initialization file. Command files passed to `--early-init-command` or `-eix` are also early initialization files, with the same command restrictions. Only commands that can appear in an early initialization file should be passed to `--early-init-eval-command` or `-eiex`.

In contrast, the general initialization files are processed later, after GDB has finished its own internal initialization process, any valid command can be used in these files.

Throughout the rest of this document the term initialization file refers to one of the general initialization files, not the early initialization file. Any discussion of the early initialization file will specifically mention that it is the early initialization file being discussed.

As the system wide and home directory initialization files are processed before most command line options, changes to settings (e.g. ‘`set complaints`’) can affect subsequent processing of command line options and operands.

The following sections describe where GDB looks for the early initialization and initialization files, and the order that the files are searched for.

#### 2.1.4.1 Home directory early initialization files

GDB initially looks for an early initialization file in the users home directory1. There are a number of locations that GDB will search in the home directory, these locations are searched in order and GDB will load the first file that it finds, and subsequent locations will not be checked.

On non-macOS hosts the locations searched are:

- The file `gdb/gdbearlyinit` within the directory pointed to by the environment variable `XDG_CONFIG_HOME`, if it is defined.
- The file `.config/gdb/gdbearlyinit` within the directory pointed to by the environment variable `HOME`, if it is defined.
- The file `.gdbearlyinit` within the directory pointed to by the environment variable `HOME`, if it is defined.

By contrast, on macOS hosts the locations searched are:

- The file `Library/Preferences/gdb/gdbearlyinit` within the directory pointed to by the environment variable `HOME`, if it is defined.
- The file `.gdbearlyinit` within the directory pointed to by the environment variable `HOME`, if it is defined.

It is possible to prevent the home directory early initialization file from being loaded using the ‘`-nx`’ or ‘`-nh`’ command line options, see Choosing Modes.

#### 2.1.4.2 System wide initialization files

There are two locations that are searched for system wide initialization files. Both of these locations are always checked:

``system.gdbinit``

  This is a single system-wide initialization file. Its location is specified with the `--with-system-gdbinit` configure option (see System-wide configuration). It is loaded first when GDB starts, before command line options have been processed.

``system.gdbinit.d``

  This is the system-wide initialization directory. Its location is specified with the `--with-system-gdbinit-dir` configure option (see System-wide configuration). Files in this directory are loaded in alphabetical order immediately after `system.gdbinit` (if enabled) when GDB starts, before command line options have been processed. Files need to have a recognized scripting language extension (`.py`/`.scm`) or be named with a `.gdb` extension to be interpreted as regular GDB commands. GDB will not recurse into any subdirectories of this directory.

It is possible to prevent the system wide initialization files from being loaded using the ‘`-nx`’ command line option, see Choosing Modes.

#### 2.1.4.3 Home directory initialization file

After loading the system wide initialization files GDB will look for an initialization file in the users home directory2. There are a number of locations that GDB will search in the home directory, these locations are searched in order and GDB will load the first file that it finds, and subsequent locations will not be checked.

On non-Apple hosts the locations searched are:

`$XDG_CONFIG_HOME/gdb/gdbinit`
`$HOME/.config/gdb/gdbinit`
`$HOME/.gdbinit`

While on Apple hosts the locations searched are:

`$HOME/Library/Preferences/gdb/gdbinit`
`$HOME/.gdbinit`

It is possible to prevent the home directory initialization file from being loaded using the ‘`-nx`’ or ‘`-nh`’ command line options, see Choosing Modes.

The DJGPP port of GDB uses the name `gdb.ini` instead of `.gdbinit` or `gdbinit`, due to the limitations of file names imposed by DOS filesystems. The Windows port of GDB uses the standard name, but if it finds a `gdb.ini` file in your home directory, it warns you about that and suggests to rename the file to the standard name.

#### 2.1.4.4 Local directory initialization file

GDB will check the current directory for a file called `.gdbinit`. It is loaded last, after command line options other than ‘`-x`’ and ‘`-ex`’ have been processed. The command line options ‘`-x`’ and ‘`-ex`’ are processed last, after `.gdbinit` has been loaded, see Choosing Files.

If the file in the current directory was already loaded as the home directory initialization file then it will not be loaded a second time.

It is possible to prevent the local directory initialization file from being loaded using the ‘`-nx`’ command line option, see Choosing Modes.

#### Footnotes

### (1)

On DOS/Windows systems, the home directory is the one pointed to by the `HOME` environment variable.

### (2)

On DOS/Windows systems, the home directory is the one pointed to by the `HOME` environment variable.

Previous: Startup, Up: Invoking GDB [Contents][Index]