diff options
| -rw-r--r-- | trash/trashspec.html | 338 |
1 files changed, 246 insertions, 92 deletions
diff --git a/trash/trashspec.html b/trash/trashspec.html index ac6d18f..7ead00c 100644 --- a/trash/trashspec.html +++ b/trash/trashspec.html @@ -5,6 +5,9 @@ <TITLE>Trash specification</TITLE> <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.0 (Linux)"> <META NAME="AUTHOR" CONTENT="Mikhail Ramendik"> + <META NAME="CREATED" CONTENT="20040909;384300"> + <META NAME="CHANGEDBY" CONTENT="òÁÍÅÎÄÉË çÒÉÇÏÒØÅ×ÉÞ"> + <META NAME="CHANGED" CONTENT="20040909;2034600"> <STYLE> <!-- P.sdfootnote { margin-left: 0.5cm; text-indent: -0.5cm; margin-bottom: 0cm; font-size: 10pt } @@ -18,7 +21,7 @@ <H3>Content by David Faure <<A HREF="mailto:dfaure@trolltech.com">dfaure@trolltech.com</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.2 +<H3>Version 0.3 </H3> <H2>Abstract</H2> <P>The purpose of this Specification is to provide a common way in @@ -72,8 +75,8 @@ 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 alphanumeric -names, is essential for this Specification. +<P>A multi-user environment, where users have specific numeric +identifiers, is essential for this Specification. </P> <P STYLE="font-weight: medium">File systems and logon systems can be case-sensitive or non-case-sensitive; therefore, systems should @@ -95,25 +98,26 @@ the question of shredding is beyond the scope of this document].</P> <P>Original filename – the name that a file (currently in the trash) had prior to getting trashed. </P> -<P>Top directory – the directory where a file system is -mounted. “/” is the top directory for the root file +<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>Home directory – the “home” directory for a -user; the user generally stores personal fines in this folder. Also -known as $HOME. In Unix-like systems, home directories are usually -located under the /home or /usr/home tree .</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" +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> @@ -121,20 +125,27 @@ in this document are to be interpreted as described in <A HREF="http://www.faqs. 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 <B>$HOME/.Trash</B> directory MUST be available<A CLASS="sdfootnoteanc" NAME="sdfootnote3anc" HREF="#sdfootnote3sym"><SUP>3</SUP></A>. -It should function as the user's Trash directory. Files that the user -trashes from the home directory, and from other directories on the -same file system (device/partition), should be stored here (see the -next section for the storage details). $HOME/.Trash SHOULD be -automatically created for 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> +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 $HOME/.Trash . 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> +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 @@ -142,82 +153,164 @@ 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 create <B>.Trash</B> directories in Top -directories of some mounted file systems. How these directories are -created (by the system administrator, a daemon, etc.) is determined -by the implementation.</P> -<P>Such .Trash directories are <I>not</I> in themselves trash storage -directories; this would break multi-user support. Instead, an -$topdir/.Trash directory can contain any number of subdirectories, -named for users that perform trashing operations; i.e. -<B>$topdir/.Trash/user</B> . Each of these is a trash storage -directory, containing the files trashed by this user. (See the next -section for the storage details).</P> -<P>Note that an implementation MAY choose to support or not support -trashing into $topdir/.Trash/user. If it does support it, it SHOULD -make it a configuration option, so that the administrator can disable -it for any or all mount points for security reasons (and use -$HOME/.Trash or no trashing at all).</P> -<P>However, if a .Trash directory does exist in any top directory, an -implementation MUST be able to list and undelete files that are in -the current user's subdirectory within it.</P> -<P>The use of $topdir/$Trash can lead to some peculiar issues. These -are discussed in the “Implementation notes” section, at -the end of this document.</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><SPAN STYLE="font-style: normal">, +to disable this checking for a particular top directory, in order to +support file systems that do not have the “sticky bit”).</SPAN></P> +<P><SPAN STYLE="font-style: normal">The implementation also MUST +check that this directory is not a symbolic link. </SPAN> +</P> +<P><SPAN STYLE="font-style: normal">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.</SPAN></P> +<P><SPAN STYLE="font-style: normal">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:</SPAN></P> +<P STYLE="margin-left: 2cm"><SPAN STYLE="font-style: normal">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. </SPAN>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><SPAN STYLE="font-style: normal">(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.</SPAN></P> +<P><SPAN STYLE="font-style: normal">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:</SPAN></P> +<P STYLE="margin-left: 2cm"><SPAN STYLE="font-style: normal">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.</SPAN></P> +<P STYLE="font-style: normal">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 +<SPAN STYLE="font-style: normal">to disable (2) completely.</SPAN></P> +<P><SPAN STYLE="font-style: normal">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.</SPAN></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 $HOME/.Trash). This trash directory will be -named “$trash” here.</P> +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="sdfootnote4anc" HREF="#sdfootnote4sym"><SUP>4</SUP></A> +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 and -modification time for a file/directory in $trash/files SHOULD be the -same as the file/directory had before getting trashed.</P> +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="sdfootnote5anc" HREF="#sdfootnote5sym"><SUP>5</SUP></A>. +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><SPAN STYLE="font-weight: medium">(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). </SPAN> +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. The contents of this file are:</P> -<PRE><I>original_location</I>\n -<I>trashing_time</I>\n</PRE><P> -Where:</P> +$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><SPAN STYLE="font-style: normal"> . Its first +line must be [Trash entry]. </SPAN> +</P> +<P STYLE="font-style: normal">It also must have two lines that are +key/value pairs as described in the Desktop Entry Specification:</P> <UL> - <LI><P><I>original_location</I> is 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 $HOME for - $HOME/.Trash); it MUST not contain “..”, and for files - not “under” that directory, absolute pathnames must be - used. - </P> - <LI><P><I>trashing_time</I> is the date and time when the - file/directory was trashed. It should be a UTC (GMT) date/time in - <A HREF="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601</A> - format: . + <LI><P STYLE="font-style: normal">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 contain “..”, 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 STYLE="font-style: normal">The value type for this key is + “localestring”; it should use the locale in which file + names are stored on this file systems, or, if this is unknown, + UTF-8.</P> + <LI><P><SPAN STYLE="font-style: normal">The key “DeletionDate<FONT FACE="Times New Roman">” + contains the date and time when the file/directory was trashed. The + date and time are to be in the </FONT></SPAN><TT><FONT FACE="Times New Roman">YYYY-MM-DDThh:mm:ss + format (see <A HREF="http://www.faqs.org/rfcs/rfc3339.html">RFC + 333<SPAN STYLE="font-style: normal">9</SPAN></A></FONT></TT><SPAN STYLE="font-style: normal">). + The time zone should be the user's (or filesystem's) local time. The + value type for this key is “string”.</SPAN></P> </UL> -<PRE STYLE="margin-bottom: 0.5cm"><I>YYYY</I>-<I>MM</I>-<I>DD</I>T<I>hh</I>:<I>mm</I>:<I>ss</I>Z</PRE> -<UL> - <LI><P>\n is the newline character.</P> -</UL> +<P STYLE="font-style: normal">Example:</P> +<PRE STYLE="font-style: normal">[Trash entry] +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 entry]) and these two key/value pairs. +If a srting 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 @@ -225,13 +318,46 @@ 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 SHOULD +create the corresponding file in $trash/info first. Moreover, it +SHOULD use O_EXCL when creating it. Before creating this file, or +before trying again if the creation fails, the implementation should +check whether a file with the same already exists; if so, the name +should be changed. (This prevents a race condition if two processes +try to trash files at the same time, and attempt to use the same file +name.)</P> <H2>Implementation notes</H2> -<P>[This section will contain notes on implementing all the basic -operations: trashing a file/directory, listing trash contents, -undeleting a file/directory, and emptying the trash. In particular, -it will describe the peculiarities of implementing the -$topdir/.Trash/user solution. I plan to write this section later, to -include the feedback in the FreeDesktop.org mailing list]</P> +<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 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> <H2>Administrativia</H2> <H3>Status of this document</H3> <P>This document is, at this moment, only a draft. It will hopefully @@ -240,17 +366,24 @@ 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>License</H3> -<P>Use and disribute 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>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.2.html">http://www.ramendik.ru/docs/trashspec.0.2.html</A> +<P><A HREF="http://www.ramendik.ru/docs/trashspec.0.3.html">http://www.ramendik.ru/docs/trashspec.0.3.html</A> is the permanent location of this version. </P> <H3>Version history</H3> @@ -259,6 +392,12 @@ is the permanent location of this version. <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” license, 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><BR><BR> </P> <DIV ID="sdfootnote1"> @@ -281,14 +420,29 @@ Dave Cridland <<A HREF="mailto:dave@cridland.net">dave@cridland.net</A>></ the case.</P> </DIV> <DIV ID="sdfootnote4"> - <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote4sym" HREF="#sdfootnote4anc">4</A>“$trash/files/”, + <P CLASS="sdfootnote"><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="sdfootnote5"> - <P CLASS="sdfootnote" STYLE="margin-bottom: 0.5cm"><A CLASS="sdfootnotesym" NAME="sdfootnote5sym" HREF="#sdfootnote5anc">5</A>At +<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"><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"><A CLASS="sdfootnotesym" NAME="sdfootnote8sym" HREF="#sdfootnote8anc">8</A>This + provides for future extension</P> +</DIV> </BODY> </HTML>
\ No newline at end of file |