Added UID, GID, permissions (#265)

doc/cache-file-format-v10.txt

@@ -0,0 +1,230 @@
+                        The QDirStat Cache File Format
+                       ================================
+
+Author:  Stefan Hundhammer <[email protected]>
+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