filesmetadata file format

Submitted by Alexis Wilke on Sat, 04/27/2013 - 02:32

The control directory of a package to be built may include a file named filesmetadata.

This is a text file that can be used to describe all the files in a package. It can even include files that you want in the package but that the project install target does not create for different reasons (i.e. symbolic links, devices, special permissions, special user & group, etc.)

This is quite handy to define many of the metadata of files in your resulting packages.

The file is text (it is taken as UTF-8, not other encoding are supported). You may include empty lines and lines that start with the hash (#) character are viewed as comments. Other lines support the following fields:

Field Format Comments
File Type and Mode -
or
trwxrwxrwx		 Similar to the output of ls -l, 10 characters: the first represents the file type, the following ones the owner, group, and other users permissions. If you do not want to specify the file type and mode, use one dash by itself.
Supported types:
Character Type
- Regular file
b Block Special
C Continuous regular file
c Character Special
d Directory
p FIFO or Pipe
h Hard Link
l Symbolic Link

The permission flags support 3 groups of 3 flags. Each group represents permissions for the user, the group, and the other users. The flags supported are:

First flag: 'r' means the corresponding user can read the file; '-' means that read permission is not given.

Second flag: 'w' means the corresponding user can write to the file; '-' means that no write permissions.

The third flag is generally: 'x' meaning that the file is executable; or '-' meaning that the file is not executable.

The third flag can also be 's' or 'S' in the owner or group positions. The 's' letter means the corresponding user or group can becomes effective while running this executable. For example, an lp tool can be given lp as a group so as to be able to access the lp device.

The third flag can also be 't' or 'T' in the other position. The 't' letter authorize anyone to create files in that directory. In most cases it is used on temporary and log directories.
Owner - or -/-
or
uid/name		 The numeric identifier of this owner (i.e. zero (0) for root), followed by a slash and the name of the user. For root, use 0/root. Either value can be set to a dash '-' in which case it is ignored. The value as a whole can be set to a single dash in which case it is considered to be '-/-'.
Group - or -/-
or
gid/name		 The numeric identifier of this group (i.e. one (1) for adm), followed by a slash and the name of the group. For adm, use 1/adm. Either value can be set to a dash '-' in which case it is ignored. The value as a whole can be set to a single dash in which case it is considered to be '-/-'.
Date YYYYMMDDTHHMMSS The last modification date for this file. The T is the actual letter T in that date.
Letters Range Meaning
YYYY 1970 to 2068 Year including the century
MM 01 to 12 Month
DD 01 to 31 Day
T   The letter T as is
HH 00 to 23 The hour
MM 00 to 59 The minute
SS 00 to 59 Second
The current Debian package format makes use of the tar format which makes use of a 32 bit time_t field which limits the year between 1970 and 2068. We are planning to release a format that support dates outside of that range.
Device - or -,-
or
major,minor		 The major and minor number of a file representing a device. Although it is not adviced to include a device in your tarballs, this allows you to do so1.
Filename name The filename including spaces if necessary, although spaces at the end of the filename are ignored. The filename must start with a slash or the format is considered invalid2.
Symbolic Link name -> link If the filename includes " -> " then it is viewed as a filename (left side) and a symbolic link destination (right side.)

The filename may start with a + character (before the slash (/) character) in which case the build operation will add this file to the data archive. This works for any type of file that does not include content (i.e. devices, symbolic links, directories, etc.)

  • 1. It is expected that you'd write a script to create such files when configuring your device. Also, under MS-Windows such files are ignored.
  • 2. Although the filename is saved as a relative path in the final archive, it is expected to be defined with a slash, and thus as a full path, in the filesmetadata file.