From 4636efe0c39c332886b8ba704e2345eba1c2a7a3 Mon Sep 17 00:00:00 2001 From: David Faure Date: Wed, 24 Apr 2013 18:36:22 +0200 Subject: Add "directorysizes" spec, bump version to 1.0 --- trash/trashspec.html | 81 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 11 deletions(-) diff --git a/trash/trashspec.html b/trash/trashspec.html index a8a977e..81c4954 100644 --- a/trash/trashspec.html +++ b/trash/trashspec.html @@ -14,11 +14,12 @@

The FreeDesktop.org Trash specification

Written by Mikhail Ramendik <mr@ramendik.ru>

Initial version written by Mikhail Ramendik <mr@ramendik.ru>

Content by David Faure <faure@kde.org>, -Alexander Larsson <alexl@redhat.com> +Alexander Larsson <alexl@redhat.com>, +Ryan Lortie <desrt@desrt.ca> and others on the FreeDesktop.org mailing list

Version 0.8

Version 1.0

Abstract

The purpose of this Specification is to provide a common way in which all “Trash can” implementations should store, list, @@ -236,7 +237,7 @@ both of them).

directories. This section concerns the contents of any trash directory (including the “home trash” directory). This trash directory will be named “$trash” here.

A trash directory contains two subdirectories, named info and +

A trash directory contains two subdirectories, named info and files.

The $trash/files directory contains the files and directories that were trashed. When a file or directory is trashed, @@ -358,14 +359,65 @@ sites and CIFS shares. In systems implementing this specification, trashing of files from such machines is to be done only to the user's home trash directory (if at all). A future version may address this limitation.

Directory size cache

In order to speed up the calculation of the total size of a given trash directory, +implementations (since version 1.0 of this specification) SHOULD create or update the +$trash/directorysizes file, which is a cache of the sizes of the directories +that were trashed into this trash directory. +Individual trashed files are not present in this cache, since their size can be determined +with a call to stat().

Each entry contains the name and size of the trashed directory, as well as the modification +time of the corresponding trashinfo file (IMPORTANT: not the modification time of the directory itself)⁹.

The size is calculated to be the disk space used by the directory and its +contents, i.e. the size of the blocks, in bytes (like `du -B1` would calculate).

The modification time is stored as an integer, the number of seconds since Epoch. Implementations should use at least 64 bits for this number in memory.

The format of the “directorysizes” file is a simple text-based format, where each line is:

+[size] [mtime] [percent-encoded-directory-name]
+

Example:

+16384 15803468 Documents
+8192 15803582 Another_Folder
+

The last entry on each line is the name of the trashed directory, stored as the +sequence of bytes produced by the file system, with characters escaped +as in URLs (as defined by RFC 2396, section 2). +Strictly speaking, percent-encoding is really only necessary for the newline character and for '%' itself. +Encoding all control characters or fully applying RFC 2396 for consistency with trashinfo files +is perfectly valid, however.

The character '/' is not allowed in the directory name (even as %2F), since all these +directories must be direct children of the "files" directory, and absolute paths are not allowed.

Implementations MUST use a temporary file followed by an atomic rename() operation in order +to avoid corruption due to two implementations writing to the file at the same time. The fact +that the changes from one of the writers could get lost isn't an issue, the cache can be updated again +later on to add that entry.

+ +

Non-normative: suggested algorithm for calculating the size of a trash directory

+ +

+load directorysizes file into memory, e.g. a hash directory_name -> (size, mtime, seen=false)
+totalsize = 0
+list "files" directory, and for each item:
+    stat the item
+    if a file:
+        totalsize += file size
+    if a directory:
+        stat the trashinfo file to get its mtime
+        lookup entry in hash
+        if no entry found or entry's cached mtime != trashinfo's mtime:
+            calculate directory size (from disk)
+            totalsize += calculated size
+            add/update entry in hash (size of directory, trashinfo's mtime, seen=true)
+        else:
+            totalsize += entry's cached size
+            update entry in hash to set seen=true
+done
+remove entries from hash which have (seen == false)
+write out hash back to directorysizes file
+

Administrativia

Status of this document

This document is, at this moment, only a draft. It will hopefully -become an official or semi-official FreeDesktop.org specification in -the future.

Date of first public distribution: August 30, 2004. This document -will serve as evidence of prior art for any patent filed after this -date.

Copyright and License

0.7 April 12, 2005. Added URL-style encoding for the name of the deleted file, as implemented in KDE 3.4

0.8 March 14, 2012. Update David Faure's email address, fix permanent URL for this spec.

1.0 April 16, 2013. Add directorysizes cache.

@@ -450,5 +503,11 @@ as implemented in KDE 3.4

8This provides for future extension

9Rationale: + if an older trash implementation restores a trashed directory, adds files to a nested subdir and trashes it again, + the modification time of the directoy didn't change, so it is not a good indicator. However the modification time + of the trashinfo file will have changed, since it is always the time of the actual trashing operation.

-- cgit v1.2.3-70-g09d2