The QDirStat Cache File Format
================================
Author: Stefan Hundhammer <Stefan.Hundhammer@gmx.de>
Updated: 2016-01-09
QDirStat can read cache files in either gzip or plain text (uncompressed)
format. The file format is line oriented.
Empty lines as well as lines with a '#' character as their first
non-whitespace character are ignored.
To generate a cache file, you can use QDirstat ("File" -> "Write Cache File")
or the supplied qdirstat-cache-writer script in the scripts/ directory of the
QDirStat sources.
Example:
[qdirstat 1.0 cache file]
# Do not edit!
#
# Type path size mtime <optional fields>
D /work/home/sh/kde/kdirstat 159 0x43aea3d3
F ChangeLog 19288 0x43ae9a3b
F .cvsignore 207 0x41c194f3
F stamp-h1 23 0x43ae9d73
F acinclude.m4 357171 0x43ae9d52
F Makefile.am 1237 0x43ad58a0
F config.h 5460 0x43ae9977
D /work/home/sh/kde/kdirstat/kdirstat 549 0x43aea73b
F .cvsignore 108 0x3b7bda58
F kcleanupcollection.cpp 7615 0x41a3322d
F kdirstatapp.cpp 24254 0x43aea372
F kdirtree.cpp 33083 0x43adc843
F kdirstatsettings.cpp 30519 0x3e39540c
F kdirtreeiterators.cpp 7191 0x3e1ad131
F ktreemapview.cpp 17100 0x3f93ee7b
D /work/home/sh/kde/kdirstat/kdirstat/.libs 24 0x43ae9900
D /work/home/sh/kde/kdirstat/kdirstat/.deps 504 0x43aea73a
F ktreemaptile.Po 18074 0x43ae99a0
F kdirtree.Po 18134 0x43aea0ba
D /work/home/sh/kde/kdirstat/kdirstat/pics 144 0x43ae9d72
F hi32-action-symlink.png 1141 0x3c0b5152
F Makefile.am 59 0x41a47537
D /work/home/sh/kde/kdirstat/kdirstat/pics/CVS 64 0x41c194fc
F Entries 447 0x41c194fc
F Repository 23 0x41c194fb
F Root 54 0x41c194fb
D /work/home/sh/kde/kdirstat/kdirstat/CVS 64 0x434657ca
F Entries 2020 0x434657ca
F Repository 18 0x41c194f8
F Root 54 0x41c194f8
(End of example)
Header
======
The first line ( "[qdirstat 1.0 cache file]" ) is a header identifying the file
format. Future versions of QDirStat may or may not check the version number
(the second word of the header line) to make sure the file format is compatible
with that particular version of QDirStat.
For compatibility reasons, QDirStat will recognize both "qdirstat" and
"kdirstat" as file format keywords.
Data Lines
==========
The data lines are separated into fields by whitespace (blanks or tabs).
Fields are not surrounded by single or double quotes.
The maximum line length is 1024 bytes.
Mandatory fields are:
- Type
- Path or name
- Size
- MTime (time of last modification)
After those mandatory fields there may be optional fields in this order:
- "blocks:" followed by a field with the number of blocks
- "links:" followed by a field with the number of links
The identifiers of those optional fields ("blocks:", "links:") are case
insensitive.
Fields
======
Type
----
Any of:
"F" plain file
"D" directory
"L" (symbolic) link
"BlockDev" block device i-node
"CharDev" character device i-node
"FIFO" FIFO (named pipe)
"Socket" socket
The type field is case insensitive.
Path or Name
------------
Either an absolute path (starting with "/") or only a base name relative to
the last preceding full path in the file.
Directory entries are required to have an absolute path. Entries for plain
files, symlinks, or special files (devices, FIFOs, sockets) may have an
absolute or a relative path.
Hint: To save some disk space with relative paths, it makes sense to
list the plain files in a directory first and then descend into any
subdirectories when writing a cache file.
Paths and names are URL-encoded, i.e. any character (in particular whitespace)
that might otherwise be some kind of delimiter is specified as its hex code
with preceding "%":
with blank -> with%20blank
with%percent -> with%25percent
Take special care for blanks, tabs, newlines, and percent characters. It
does not hurt to escape a few more characters than would strictly be
necessary.
As for encoding, unfortunately this is one big mess. 7 bit ASCII works
alright, but if there are any special characters, everything depends on the
locale in which the user created a file. There is no standard for file name
encodings in file systems; special characters may come in all kinds of
flavours - in Latin-1 (ISO-8859-1), Latin-2, UTF-8, Japanese, Korean, Chinese,
whatever. In an ideal world, the file system would take care about this and
normalize file names with non-ASCII (7 bit) characters, but that doesn't
happen. So if one user uses, say, Latin-1 and another uses UTF-8, a file system
may have files with different encodings for each file name. Worse yet, the same
(special, i.e. non-7-bit-ASCII) character will be be stored in different
character representations for different file names.
Those character representations is what readdir() returns. There is no way to
tell in which encoding a name may come, so there is also no way to convert it
to a well-defined standard encoding like, say, UTF-8. So what gets stored in
the cache file is the same byte sequence as returned by readdir(). Those names
encoded in something other than the current locale of KDE where QDirStat is
running will of course be displayed with garbage letters, but this cannot be
helped. This is just the same as when the name is read directly from the file
system with readdir(). Bad luck.
Size
----
The entry's size (st_size in struct stat as returned by lstat() ).
Note: This is the entry's own size, not the accumulated size of all
children!
This size is given in bytes. It may also have a trailing unit (directly
following the number, without whitespace):
- "K" for kB (1024 bytes)
- "M" for MB (1024 kB)
- "G" for GB (1024 MB)
The size is always specified in integer numbers, never in fractional
numbers. So if it cannot be divided by a bigger unit without a fractional
part, use the next-lower unit that fits without fraction.
Examples:
1024 -> 1K
1025 -> 1025 (NOT 1.01K or something like this!)
8589934592 -> 8G
8589934593 -> 8589934593 (bad luck)
MTime
------
The entry's last modification time as time_t, i.e., in seconds since
1970-01-01 00:00:00.
May be specified in hex (with preceding 0x) or decimal.
Blocks
------
If a file is a sparse file (and only then) it has a "blocks:" field.
This is the content of the st_blocks field of struct stat as returned by
lstat(): The number of disk blocks actually allocated.
This number multiplied by the block size may be less than what st_size
returns; in this case that file is considered to be a "sparse" file or a
file with "holes".
A block size of 512 bytes is assumed.
Example:
blocks: 17
This file has 17*512 bytes allocated.
Links
-----
If a non-directory entry has more than one hard link, the entry has a
"links:" field indicating the number of hard links:
links: 7
Generated by dwww version 1.15 on Thu May 23 11:15:45 CEST 2024.