7.37 .file

There are two different versions of the .file directive. Targets that support DWARF2 line number information use the DWARF2 version of .file. Other targets use the default version.

Default Version

This version of the .file directive tells as that we are about to start a new logical file. The syntax is:

.file string

string is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes ‘"’; but if you wish to specify an empty file name, you must give the quotes–"". This statement may go away in future: it is only recognized to be compatible with old as programs.

DWARF2 Version

When emitting DWARF2 line number information, .file assigns filenames to the .debug_line file name table. The syntax is:

.file fileno filename

The fileno operand should be a unique positive integer to use as the index of the entry in the table. The filename operand is a C string literal enclosed in double quotes. The filename can include directory elements. If it does, then the directory will be added to the directory table and the basename will be added to the file table.

The detail of filename indices is exposed to the user because the filename table is shared with the .debug_info section of the DWARF2 debugging information, and thus the user must know the exact indices that table entries will have.

If DWARF5 support has been enabled via the -gdwarf-5 option then an extended version of .file is also allowed:

.file fileno [dirname] filename [md5 value]

With this version a separate directory name is allowed, although if this is used then filename should not contain any directory component, except for fileno equal to 0: in this case, dirname is expected to be the current directory and filename the currently processed file, and the latter need not be located in the former. In addition an MD5 hash value of the contents of filename can be provided. This will be stored in the the file table as well, and can be used by tools reading the debug information to verify that the contents of the source file match the contents of the compiled file.