1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=us-ascii">
<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: 10pt }
A.sdfootnoteanc { font-size: 57% }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1>The FreeDesktop.org Trash specification</H1>
<H3><SPAN>By Mikhail Ramendik <<A HREF="mailto:mr@ramendik.ru">mr@ramendik.ru</A>></SPAN></H3>
<H3>Version 0.1 “First Try”</H3>
<H4>Based on network discussion 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.</H4>
<H2>Overview</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>The purpose of this Specification is to provide a
common way in which all Trash can implementation 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>
<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 alphanumeric names, is essential for this
Specification.
</P>
<P LANG="en-US" STYLE="font-weight: medium">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 – 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>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>MUST – an
implementation has to do this in order to be in compliance with this
Specification.</P>
<P>SHOULD – doing this
is recommended, but not required.</P>
<P>MAY – doing this is
optional.</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 <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 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>
<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>
<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 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>
<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>
<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>
. 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>
<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>.
A filename in the $trash/files directory MUST NEVER be used to
recover the original filename </B>(except in an emergency case when
an info file has been lost; this case must be clearly marked to the
user as an emergency).
</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>
<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: .
</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>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>
<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>
<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>License</H3>
<P>Use 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>Redistribution and 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.1.html">http://www.ramendik.ru/docs/trashspec.0.1.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>
<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>“$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
least because another implementation might trash files into the same
trash directory</P>
</DIV>
</BODY>
</HTML>
|