23.2.3.1 The objfile-gdb.py file

When a new object file is read, gdb looks for a file named objfile-gdb.py, where objfile is the object file's real name, formed by ensuring that the file name is absolute, following all symlinks, and resolving . and .. components. If this file exists and is readable, gdb will evaluate it as a Python script.

If this file does not exist, and if the parameter debug-file-directory is set (see Separate Debug Files), then gdb will look for real-name in all of the directories mentioned in the value of debug-file-directory.

Finally, if this file does not exist, then gdb will look for a file named data-directory/python/auto-load/real-name, where data-directory is gdb's data directory (available via show data-directory, see Data Files), and real-name is the object file's real name, as described above.

gdb does not track which files it has already auto-loaded this way. gdb will load the associated script every time the corresponding objfile is opened. So your -gdb.py file should be careful to avoid errors if it is evaluated more than once.