diff options
| author | David Faure <faure@kde.org> | 2012-02-17 17:37:07 +0100 |
|---|---|---|
| committer | David Faure <faure@kde.org> | 2012-02-17 17:37:07 +0100 |
| commit | a4de04356ed9eb60a47e6db3ff1f7de8893e9a18 (patch) | |
| tree | 9e2df3d00023be21fda0dd877334693bac869cc7 | |
| parent | fd333933a44b7984425721da47310ec9f5fb9aca (diff) | |
| download | xdg-specs-a4de04356ed9eb60a47e6db3ff1f7de8893e9a18.tar.xz | |
trash: Import spec from http://www.ramendik.ru/docs/trashspec.html
| -rw-r--r-- | trash/trashspec.html | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/trash/trashspec.html b/trash/trashspec.html new file mode 100644 index 0000000..0950084 --- /dev/null +++ b/trash/trashspec.html @@ -0,0 +1,457 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=koi8-r"> + <TITLE>Trash specification</TITLE> + <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.0 (Linux)"> + <META NAME="AUTHOR" CONTENT="Mikhail Ramendik"> + <STYLE> + <!-- + P.sdfootnote { margin-left: 0.5cm; text-indent: -0.5cm; margin-bottom: 0cm; font-size: 80% } + A.sdfootnoteanc { font-size: 57% } + --> + </STYLE> +</HEAD> +<BODY LANG="en-US" DIR="LTR"> +<H1>The FreeDesktop.org Trash specification</H1> +<H3>Written by Mikhail Ramendik <<A HREF="mailto:mr@ramendik.ru">mr@ramendik.ru</A>></H3> +<H3>Content by David Faure <<A HREF="mailto:faure@kde.org">faure@kde.org</A>>, +Alexander Larsson <<A HREF="mailto:alexl@redhat.com">alexl@redhat.com</A>> +and others on the FreeDesktop.org mailing list</H3> +<H3>Version 0.7</H3> +<H2>Abstract</H2> +<P>The purpose of this Specification is to provide a common way in +which all “Trash can” implementations should store, list, +and undelete trashed files. By complying with this Specification, +various Trash implementations will be able to work with the same +devices and use the same Trash storage. For example, if one +implementation sends a file into the Trash can, another will be able +to list it, undelete it, or clear it from the Trash.</P> +<H2>Introduction</H2> +<P>An ability to recover accidentally deleted files has become the de +facto standard for today's desktop user experience. +</P> +<P>Users do not expect that anything they delete is permanently gone. +Instead, they are used to a “Trash can” metaphor. A +deleted document ends up in a “Trash can”, and stays +there at least for some time — until the can is manually or +automatically cleaned. +</P> +<P>This system has its own problems. Notably, cleaning disk space +becomes a two-step operation — delete files and empty trash; +this can lead to confusion for inexperienced users (“what's +taking up my space?!”). Also, it is not easy to adapt the +system to a multiuser environment. Besides, there is a potential for +abuse by uneducated users — anecdotal evidence says they +sometimes store important documents in the Trash can, and lose them +when it gets cleaned!</P> +<P>However, the benefits of this system are so great, and the user +expectation for it so high, that it definitely should be implemented +on a free desktop system. And in fact, several implementations +already exist — some as command line utilities, some as +preloaded libraries, and some as parts of major desktop environments. +For example, both Gnome and KDE have their own trash mechanisms.</P> +<P>This Specification is to provide a common way in which all Trash +can implementations should store trashed files. By complying with +this Specification, various Trash implementations will be able to +work with the same devices and use the same Trash storage. +</P> +<P>This is important, at least, for shared network resources, +removable devices, and in cases when different implementations are +used on the same machine at different moments (i.e. some users prefer +Gnome, others prefer KDE, and yet others are command-line fans).</P> +<H2>Scope and limitations</H2> +<P>This Specification only describes the Trash storage. It does <B>not</B> +limit the ways in which the actual implementations should operate, as +long as they use the same Trash storage. Command line utilities, +desktop-integrated solutions and preloaded libraries can work with +this specification. <A CLASS="sdfootnoteanc" NAME="sdfootnote1anc" HREF="#sdfootnote1sym"><SUP>1</SUP></A></P> +<P>This Specification is geared towards the Unix file system tree +approach. However, with slight modifications, it can easily be used +with another kind of file system tree (for example, with drive +letters). +</P> +<P>A multi-user environment, where users have specific numeric +identifiers, is essential for this Specification. +</P> +<P>File systems and logon systems can be +case-sensitive or non-case-sensitive; therefore, systems should +generally not allow user names that differ only in case.</P> +<H2>Definitions</H2> +<P>Trash, or Trash can — the storage of files that were trashed +(“deleted”) by the user. These files can be listed, +undeleted, or cleaned from the trash can.</P> +<P>Trashing — a “delete” operation in which files +are transferred into the Trash can.</P> +<P>Erasing — an operation in which files (possibly already in +the Trash can) are removed (unlinked) from the file system. An erased +file is generally considered to be non-recoverable; the space used by +this file is freed. [A “shredding” operation, physically +overwriting the data, may or may not accompany an erasing operation; +the question of shredding is beyond the scope of this document].</P> +<P>Original location — the name and location that a file +(currently in the trash) had prior to getting trashed.</P> +<P>Original filename — the name that a file (currently in the +trash) had prior to getting trashed. +</P> +<P>Top directory , $topdir — the directory where a file system +is mounted. “/” is the top directory for the root file +system, but not for the other mounted file systems. For example, +separate FSes can be mounted on “/home”, “/mnt/flash”, +etc. In this text, the designation “$topdir” is used for +“any top directory”.</P> +<P>User identifier , $uid — the numeric user identifier for a +user. $uid is used here as “the numeric user identifier of the +user who is currently logged on”.</P> +<P>Trash directory — a directory where trashed files, as well +as the information on their original name/location and time of +trashing, are stored. There may be several trash directories on one +system; this Specification defines their location and contents. In +this text, the designation “$trash” is used for “any +trash directory”.</P> +<P>“Home trash” directory — a user's main trash +directory. Its name and location is defined in this document.</P> +<P>The key words "MUST", "MUST NOT", "REQUIRED", +"SHALL", "SHALL NOT", "SHOULD", "SHOULD +NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in <A HREF="http://www.faqs.org/rfcs/rfc2119.html">RFC +2119</A>.</P> +<H2>Trash directories</H2> +<P>A system can have one or more trash directories. The contents of +any trash directory are to be compliant with the same standard, +described below.</P> +<P>For every user<A CLASS="sdfootnoteanc" NAME="sdfootnote2anc" HREF="#sdfootnote2sym"><SUP>2</SUP></A> +a “home trash” directory MUST be available<A CLASS="sdfootnoteanc" NAME="sdfootnote3anc" HREF="#sdfootnote3sym"><SUP>3</SUP></A>. +Its name and location are $XDG_DATA_HOME/Trash ; $XDG_DATA_HOME is +the base directory for user-specific data, as defined in the <A HREF="http://www.freedesktop.org/Standards/basedir-spec">Desktop +Base Directory Specification</A> . +</P> +<P>The “home trash” should function as the user's main +trash directory. Files that the user trashes from the same file +system (device/partition) should be stored here (see the next section +for the storage details). A “home trash” directory SHOULD +be automatically created for any new user. If this directory is +needed for a trashing operation but does not exist, the +implementation SHOULD automatically create it, without any warnings +or delays.</P> +<P>The implementation MAY also support trashing files from the rest +of the system (including other partitions, shared network resources, +and removable devices) into the “home trash” directory . +This is a “failsafe” method: trashing works for all file +locations, the user can not fill up any space except the home +directory, and as other users generally do not have access to it, no +security issues arise.</P> +<P>However, this solution leads to costly file copying (between +partitions, over the network, from a removable device, etc.) A delay +instead of a quick “delete” operation can be unpleasant +to users.</P> +<P>An implementation may choose not to support trashing in some of +these cases (notably on network resources and removable devices). +This is what some well known operating systems do.</P> +<P>It may also choose to provide trashing in the “top +directories” of some or all mounted resources. This trashing is +done in two ways, described below as (1) and (2). +</P> +<P>(1) An administrator can create an $topdir/.Trash directory. The +permissions on this directories should permit all users who can trash +files at all to write in it.; and the “sticky bit” in the +permissions must be set, if the file system supports it. +</P> +<P>When trashing a file from a non-home partition/device<A CLASS="sdfootnoteanc" NAME="sdfootnote4anc" HREF="#sdfootnote4sym"><SUP>4</SUP></A> +, an implementation (if it supports trashing in top directories) MUST +check for the presence of $topdir/.Trash.</P> +<P>When preparing a list of all trashed files (i.e. to show to the +user), an implementation also MUST check for .Trash in all top +directories that are known to it.</P> +<P>If this directory is present, the implementation MUST, by default, +check for the “sticky bit”. (It MAY provide a way for the +administrator, <I>and only the administrator</I>, to disable this +checking for a particular top directory, in order to support file +systems that do not have the “sticky bit”).</P> +<P>The implementation also MUST check that +this directory is not a symbolic link. +</P> +<P>If any of these checks fail, the +implementation MUST NOT use this directory for either trashing or +undeleting files, even is an appropriate $uid directory (see below) +already exists in it. Besides, the implementation SHOULD report the +failed check to the administrator, and MAY also report it to the +user.</P> +<P>The following paragraph applies ONLY to +the case when the implementation supports trashing in the top +directory, and a $topdir/.Trash exists and has passed the checks:</P> +<P STYLE="margin-left: 2cm">If the directory exists and passes the +checks, a subdirectory of the $topdir/.Trash directory is to be used +as the user's trash directory for this partition/device. The name of +this subdirectory is the numeric identifier of the current user +($topdir/.Trash/$uid). When trashing a file, if this directory does +not exist for the current user, the implementation MUST immediately +create it, without any warnings or delays for the user.</P> +<P>(2) If an $topdir/.Trash directory is +absent, an $topdir/.Trash-$uid directory is to be used as the user's +trash directory for this device/partition. $uid is the user's numeric +identifier.</P> +<P>The following paragraph applies ONLY to +the case when the implementation supports trashing in the top +directory, and a $topdir/.Trash does not exist or has not passed the +checks:</P> +<P STYLE="margin-left: 2cm">When trashing a file, +if an $topdir/.Trash-$uid directory does not exist, the +implementation MUST immediately create it, without any warnings or +delays for the user.</P> +<P>When trashing a file, if this directory +does not exist for the current user, the implementation MUST +immediately create it, without any warnings or delays for the user.</P> +<P><B>Notes.</B> If an implementation provides trashing in top +directories at all, it MUST support both (1) and (2). +</P> +<P>If an implementation does NOT provide such trashing, and does +provide the user with some interface to view and/or undelete trashed +files, it SHOULD make a “best effort” to show files +trashed in top directories (by both methods) to the user, among other +trashed files or in a clearly accessible separate way.</P> +<P>When trashing a file, if the method (1) fails at any point — +i.e. the $topdir/.Trash directory does not exist, or it fails the +checks, or the system refuses to create an $uid directory in it — +the implementation MUST, by default, fall back to method (2), +described below. Except for the case when $topdir/.Trash fails the +checks, the fallback must be immediate, without any warnings or +delays. The implementation MAY, however, a way for the administrator +to disable (2) completely.</P> +<P>If both (1) and (2) fail (i.e. no +$topdir/.Trash directory exists, and an attempt to create +$topdir/.Trash-$uid fails), the implementation MUST either trash the +file into the user's “home trash” or refuse to trash it. +The choice between these options can be pre-determined, or it can +depend on the particular situation (i.e. No trashing of very large +files). However, if an implementation refuses to trash a file after a +user action that generally causes trashing, it MUST clearly warn the +user about this, and request confirmation for the action.</P> +<P>For showing trashed files, implementations SHOULD support (1) and +(2) at the same time (i.e. if both $topdir/.Trash/$uid and +$topdir/.Trash-$uid are present, it should list trashed files from +both of them).</P> +<H2>Contents of a trash directory</H2> +<P>The previous section has described the location of trash +directories. This section concerns the contents of any trash +directory (including the “home trash” directory). This +trash directory will be named “$trash” here.</P> +<P>A trash directory contains two subdirectories, named <B>info </B>and +<B>files</B>.</P> +<P>The <B>$trash/files</B> directory contains the files and +directories that were trashed. When a file or directory is trashed, +it MUST be moved into this directory<A CLASS="sdfootnoteanc" NAME="sdfootnote5anc" HREF="#sdfootnote5sym"><SUP>5</SUP></A> +. The names of files in this directory are to be determined by the +implementation; the only limitation is that they must be unique +within the directory. <I>Even if a file with the same name and +location gets trashed many times, each subsequent trashing must not +overwrite a previous copy. </I>The access rights, access time, +modification time and extended attributes (if any) for a +file/directory in $trash/files SHOULD be the same as the +file/directory had before getting trashed.</P> +<P><B>IMPORTANT NOTE. While an implementation may choose to base +filenames in the $trash/files directory on the original filenames, +this is never to be taken for granted<A CLASS="sdfootnoteanc" NAME="sdfootnote6anc" HREF="#sdfootnote6sym"><SUP>6</SUP></A>. +A filename in the $trash/files directory MUST NEVER be used to +recover the original filename; use the info file (see below) for +that. </B>(If an info file corresponding to a file/directory in +$trash/files is not available, this is an emergency case, and MUST be +clearly presented as such to the user or to the system +administrator). +</P> +<P>The <B>$trash/info </B>directory contains an “information +file” for every file and directory in $trash/files. This file +MUST have exactly the same name as the file or directory in +$trash/files, plus the extension “.trashinfo”<A CLASS="sdfootnoteanc" NAME="sdfootnote7anc" HREF="#sdfootnote7sym"><SUP>7</SUP></A>. +</P> +<P>The format of this file is similar to the format of a desktop +entry file, as described in the <A HREF="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop +Entry Specification</A> . Its first line must be [Trash Info]. +</P> +<P>It also must have two lines that are +key/value pairs as described in the Desktop Entry Specification:</P> +<UL> + <LI><P>The key “Path” + contains the original location of the file/directory, as either an + absolute pathname (starting with the slash character “/”) + or a relative pathname (starting with any other character). A + relative pathname is to be from the directory in which the trash + directory resides (i.e., from $XDG_DATA_HOME for the “home + trash” directory); it MUST not include a “..” + directory, and for files not “under” that directory, + absolute pathnames must be used. The system SHOULD only support + absolute pathnames in the “home trash” directory, not in + the directories under $topdir. + </P> + <P>The value type for this key is + “string”; it should store the file name as the + sequence of bytes produced by the file system, with characters escaped + as in URLs (as defined by <A HREF="http://www.faqs.org/rfcs/rfc2396.html">RFC +2396</A>, section 2).</P> + <LI><P>The key “DeletionDate” contains + the date and time when the file/directory was trashed. The date and + time are to be in the YYYY-MM-DDThh:mm:ss + format (see <A HREF="http://www.faqs.org/rfcs/rfc3339.html">RFC + 3339</A>). The time zone should be the user's (or + filesystem's) local time. The value type for this key is “string”.</P> +</UL> +<P>Example:</P> +<PRE>[Trash Info] +Path=foo/bar/meow.bow-wow +DeletionDate=20040831T22:32:08</PRE><P> +The implementation MUST ignore any other lines in this file, except +the first line (must be [Trash Info]) and these two key/value pairs. +If a string that starts with “Path=” or “DeletionDate=” +occurs several times, the first occurence is to be used.<A CLASS="sdfootnoteanc" NAME="sdfootnote8anc" HREF="#sdfootnote8sym"><SUP>8</SUP></A></P> +<P>Note that $trash/info has no subdirectories. For a directory in +$trash/files, only an information file for its own name is needed. +This is because, when a subdirectory gets trashed, it must be moved +to $trash/files with its entire contents. The names of the files and +directories within the directory MUST NOT be altered; the +implementation also SHOULD preserve the access and modification time +for them.</P> +<P>When trashing a file or directory, the implementation MUST create +the corresponding file in $trash/info first. When trashing a file or +directory, the implementation MUST create thecorresponding file in +$trash/info first. Moreover, it MUST try to do this in an atomic +fashion, so that if two processes try trash files with the same +filename this will result in two different trash files. On Unix-line +systems this is done by generating a filename, and then opening with +O_EXCL. If that succeeds the creation was atomic (at least on the +same machine), if it fails you need to pick another filename.</P> +<H2>Implementation notes</H2> +<P>The names of the files/directories in $trash/info SHOULD be +somehow related to original file names. This can help manual recovery +in emergency cases (for example, if the corresponding info file is +lost).</P> +<P>When trashing a file or directory, the implementation should check +whether the user has the necessary permissions to delete it, before +starting the trashing operation itself.</P> +<P>When copying, rather than moving, a file into the trash (i.e. When +trashing to the “home trash” from a different partition), +exact preservation of permissions might be impossible. Notably, a +file.directory that was owned by another user will now be owned by +this user (changing owners is usually only available to root). This +should not cause the trashing operation to fail.</P> +<P>In this same situation, setting the permissions should be done +<I>after</I> writing the copied file, as they may make it +unwriteable..</P> +<P>A trashing operation might be refused because of insufficient +permissions, even when the user does have the right to delete a file +or directory. This may happen when the user has the right to delete a +file/directory, but not to read it (or, in the case of a directory, +to list it). In this case, the best solution is probably to warn the +user, offering options to delete the file/directory or leave it +alone.</P> +<P>Automatic trash cleaning may, and probably eventually should, be +implemented. But the implementation should be somehow known to the +user.</P> +<P>If a directory was trashed in its entirety, it is easiest to +undelete it or remove it from the trash only in its entirety as well, +not as separate files. The user might not have the permissions to +delete some files in it even while he does have the permission to +delete the directory!</P> +<P><B>Important note on scope</B>. This specification currently does +NOT define trashing on remote machines where multiuser permissions +are implemented but the numeric user ID is not supported, like FTP +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.</P> +<H2>Administrativia</H2> +<H3>Status of this document</H3> +<P>This document is, at this moment, only a draft. It will hopefully +become an official or semi-official FreeDesktop.org specification in +the future.</P> +<P>Date of first public distribution: August 30, 2004. This document +will serve as evidence of prior art for any patent filed after this +date.</P> +<H3>Copyright and License</H3> +<P>Copyright (C) 2004 Mikhail Ramendik , <A HREF="mailto:mr@ramendik.ru">mr@ramendik.ru</A> +. +</P> +<P>The originators of the ideas that are described here did not +object to this copyright. The author is ready to transfer the +copyright to a standards body that would be committed to keeping this +specification, or any successor to it, an open standard.</P> +<P>The license: Use and distribute as you wish. If you make a +modified version and redistribute it, (a) keep the name of the author +and contributors somewhere, and (b) indicate that this is a modified +version.</P> +<P>Implementation under any license at all is explicitly allowed.</P> +<H3>Location</H3> +<P><A HREF="http://www.ramendik.ru/docs/trashspec.html">http://www.ramendik.ru/docs/trashspec.html</A> +. If this document gets hosted by FreeDesktop.org, a link to the page +will still be available at this location.</P> +<P><A HREF="http://www.ramendik.ru/docs/trashspec.0.7.html">http://www.ramendik.ru/docs/trashspec.0.7.html</A> +is the permanent location of this version. +</P> +<H3>Version history</H3> +<P>0.1 “First try”, August 30, 2004. Initial draft. +“Implementation notes” not written as yet.</P> +<P>0.2 August 30, 2004. Updated with feedback by Alexander Larsson +<<A HREF="mailto:alexl@redhat.com">alexl@redhat.com</A>> and by +Dave Cridland <<A HREF="mailto:dave@cridland.net">dave@cridland.net</A>></P> +<P>0.3 September 8, 2004. Changed the name and location of the “home +trash” directory, and introduced the generic term “home +trash”. Changed the trash info file format to a .desktop-like +one. Added directions on creation of info files and copying of +trashed files. Changed user names to user ids. Added implementation +notes. Added a copyright notice.</P> +<P>0.4 September 9, 2004. Changed [Trash entry] to [Trash info] and +fixed some typo's</P> +<P>0.5 September 9, 2004. Changed [Trash info] to [Trash Info]</P> +<P>0.6 October 8, 2004. Corrections by Alexander Larsson +<<A HREF="mailto:alexl@redhat.com">alexl@redhat.com</A>> . Also +added “note on scope”. Cleaned up HTML. Added a link to this +document on the freedesktop.org standards page</P> +<P>0.7 April 12, 2005. Added URL-style encoding for the name of the deleted file, +as implemented in KDE 3.4</P> +<P><BR><BR> +</P> +<DIV ID="sdfootnote1"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote1sym" HREF="#sdfootnote1anc">1</A>However, + developers of preloaded libraries should somehow work around the + case when a desktop environment also supporting the Trash + specification is run on top of them. “Double trashing” + and “trashing of the trash” should be avoided.</P> +</DIV> +<DIV ID="sdfootnote2"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote2sym" HREF="#sdfootnote2anc">2</A>To + be more precise, for every user who can use the trash facility. In + general, all human users, and possibly some “robotic” + ones like ftp, should be able to use the trash facility. + </P> +</DIV> +<DIV ID="sdfootnote3"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote3sym" HREF="#sdfootnote3anc">3</A>Note + the dot in the beginning, and for case sensitive file systems, note + the case.</P> +</DIV> +<DIV ID="sdfootnote4"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote4sym" HREF="#sdfootnote4anc">4</A>To + be more precise, from a partition/device different from the one on + which $XDG_DATA_HOME resides. + </P> +</DIV> +<DIV ID="sdfootnote5"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote5sym" HREF="#sdfootnote5anc">5</A>“$trash/files/”, + <B>not </B>into “$trash/” as in many existing + implementations!</P> +</DIV> +<DIV ID="sdfootnote6"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote6sym" HREF="#sdfootnote6anc">6</A>At + least because another implementation might trash files into the same + trash directory</P> +</DIV> +<DIV ID="sdfootnote7"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote7sym" HREF="#sdfootnote7anc">7</A>For + example, if the file in $trash/files is named foo.bar , the + corresponding file in $trash/info must be named foo.bar.trashinfo</P> +</DIV> +<DIV ID="sdfootnote8"> + <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote8sym" HREF="#sdfootnote8anc">8</A>This + provides for future extension</P> +</DIV> +</BODY> +</HTML> |