Formats support by the different "Files" fields

Files Field Formats

Supported file formats:

Format Name Line Format Default for Field Default by Count
list <filename>   1
modelist <mode> <filename>    
longlist <mode> <size> <md5sum> <filename>   4
conffiles <filename> <md5sum> Conf-Files 2
sources / md5sum <md5> <size> <filename> Files 3
sha1 <sha1> <size> <filename> Checksum-Sha1  
sha256 <sha256> <size> <filename> Checksum-Sha256  
metadata <mode> <user> <group> <size> <mtime> <filename>   6

I think that most of everything is pretty self explanatory. The following entries describe the different fields and columns in detail.

Filtering by Architecture (Not Debian Compatible)

It is possible, for all formats, to include an architecture specification. This is done by adding a list of architectures at the end of the line format. This field is always optional. It must start and end with square brackets and be the last field on the line.

The supported format is exactly the same as the architecture specification of the Depends fields: a list of architecture names separated by spaces, eventually negated. For example, for a file that is required under Linux, one would write:

Requires: list
 /usr/bin/bash [linux]

This means the package can be installed on Linux only if file /usr/bin/bash exists.

The system accepts the special case [any] so the system supports filenames that end with a square bracket.

The <mode> Entry

The <mode> is a set of 10 characters that represent a Unix mode as shown by the ls -l command. The first character defines the file type, and the following 9 represent 3 groups of 3 characters repersenting the owner, group, and other user read, write, execute permissions.

For example, a directory would generally have a mode as follow:

drwxr-xr-w 0 0123456789abcdef0123456789abcdef /usr/shared

The supported types (first character) are:

Chracter Type Description
d Directory
- Regular file
p Pipe, also called FIFO
b Block based device
c Character based device

The <user> and <group> Fields

The user and group are defined as <username>/<uid> and <groupname>/<gid>. This is particularly useful when you want to indicate the owner and group information of a file without having to do that on a local install (because a local install will not be capable of making files owner by root.)

For example, you could define a file owned by root as:

drwxr-xr-x root/0 root/0 0 20130101 /usr

The <mtime> Field

The modification time uses one of two formats: date only, or date and time.

YYYYmmDD
YYYYmmDDTHHMMSS

The fields in the date and time are:

Field Comment
YYYY Year between 1970 and 2067.
mm The month between 01 and 12. The leading 0 for January to September is required.
DD The day of the month between 01 and 31. The leading 0 for day 1 to 9 is mandatory.
T The capital letter T. This letter does not appear when only a date is defined.
HH The hour between 00 and 23. The leading 0 for hours under 10 is required.
MM The minute between 00 and 59. The leading 0 for minutes under 10 is required.
SS The second between 00 and 59. The leading 0 for seconds under 10 is required.

The <size> Field

The <size> parameter is a decimal number in all cases except for the metadata format. In this one case the size field can be used to define a device major and minor numbers. The metadata parsing checks the size field, if it includes a comma, then it is taken as a device definition and it is expected to use the format:

<major>,<minor>

where both <major> and <minor> are decimal numbers.

The metadata Format

The metadata format expects any field to be either the expected value or a dash (-). A dash means that the field is not set. So it is possible to write a field in a metadata format and yet only enter filenames.

Default for Field

When not specifying a format for a files field, the system first tries to determine whether the field has a known default format (as shown in the "Default for Field" column), if so, then that format is used.

For example, a package with one executable and one documentation file would define a Files field that looks like this:

Files:
 0123456789ABCDEF0123456789ABCDEF 12329 /usr/bin/application.exe
 0123456789ABCDEF0123456789ABCDEF 968 /usr/share/doc/application/readme.txt

When you want to use a different format than the default, specify it on the first line (Not Debian Compatible):

Files: longlist
 -r-xr-xr-x 12329 0123456789ABCDEF0123456789ABCDEF /usr/bin/application.exe
 -r--r--r-- 968 0123456789ABCDEF0123456789ABCDEF /usr/share/doc/application/readme.txt

Note that in these two cases the number of fields on each line must match the format one to one.

Default by Count

The "Default by Count" is used when a field without a specific format is queried. So for example if you defined a Temporary-Files field as follow:

Temporary-Files:
 /etc/wpkg/wpkg.conf

Then the system recognizes the lone file name (i.e. 1 word) as a list entry. This works with 1 to 4 words.

The "Default by Count" is not used by fields that have a default format such as the Files, Checksums-Sha1, Conf-Files, etc.

Long List Details

The long list format is used to list all the data.tar.gz files in a binary package. This allows us to avoid loading the whole data.tar.gz archive to check for overwrites (upgrades or packages in conflict) and file sizes (disk full check.)

Filenames with Spaces

To enter a filename with a space, encapsulate the name between double quote as in:

Files:
 0123456789ABCDEF0123456789 345 "C:\Windows\System\This File.txt"

The system still expects spaces before and/or after the filename if the format expects it.

Quotes are not necessary for the simple list format because the entire line is used as the filename.