packages icon
libtrash - a shared library to implement a "recycle bin"
--------   or "trash can" under GNU/Linux.
	   
Written by Manuel Arriaga (m.arriaga@ip.pt).

Copyright (C) 2001 Manuel Arriaga
Licensed under the GNU General Public License version 2.  See the file 
COPYING for details.


Version: 0.2 (2001-08-11)
-------

See CHANGE.LOG for details.


DESCRIPTION:
-----------

libtrash is a shared library which, when preloaded, will intercept calls to
glibc's unlink() and make sure that the specified file won't be permanently
removed but rather moved to a "trash can". It also allows the super user to
mark certain directories as "unremovable", which means that requests to
unlink files under them will always fail, even if they were issued by root.

(This last feature is meant as a higher-level substitute for ext2fs'
"immutable" flag for use by those of us who rely on other file systems.)

A companion script called hardrm is also provided; it simply passes along
its arguments to the program rm after having temporarily suspended libtrash,
which results in the _effective_ deletion of those files. I suggest that you
don't even put it in your path, otherwise you might get used to using it
instead of the "usual" rm, and then there won't be anything libtrash will be
able to do for you if you let your fingers slip.

If, at the command line, you need to issue one command with libtrash
disabled, just prepend it with 

LD_PRELOAD=""

E.g., to permanently remove remove the file "test.txt" while libtrash is
active, you could either invoke hardrm or type

LD_PRELOAD="" rm test.txt

(This is how hardrm works.)

An alternative to this method is mentioned below.

libtrash works with any GNU/Linux program which calls glibc's unlink() when
it needs to remove a file; therefore, it works seamlessly at the console and
under XFree86, independently of the programming language the program was
written in (unless, of course, it uses its own, low-level, deletion
routine).


INSTALLATION:
------------

To configure:


1 - Edit the Makefile if you wish to change the directory in which the
library will be stored (default: /usr/local/lib).

2 - Edit the section marked "Configuration" near the top of libtrash.c. All
compile-time options are verbosely explained there.



To compile:

3 - Run "make".



To install:

4 - Run, as root, "make install".

This copies libtrash-0.2 to the directory specified at the top of the
Makefile and runs ldconfig. hardrm isn't installed by default.



To activate libtrash:

5 - So that calls to unlink() are intercepted, you must "preload" this
library. This is done by running the following command whenever you log in:

export LD_PRELOAD=path_of_symlink_to_libtrash

where path_of_symlink_to_libtrash should be substituted with the real path
to that symbolic link (if you didn't modify the INSTLIBDIR variable in the
Makefile, that would be "/usr/local/lib/libtrash.so.0"). This can be
achieved in a painless way by appending that line to a file which gets
executed whenever you log in, such as ~/.profile or ~/.bash_login. If you
wish to activate libtrash for every user on the system, append that line to
/etc/profile instead. (Note: Your distribution might use different files for
this purpose. If you use a shell other than Bash, you probably know what to
do in your situation.)


----------

libtrash should now be set up and ready to spare you a lot of headaches. You
can test drive it with the following commands (assuming that you didn't
change TRASH_CAN to a string other than "Trash"):

$ touch test_file
$ rm test_file
$ ls Trash/

test_file should now be stored in Trash/. But don't be fooled by this
example! libtrash isn't restricted to "saving" files which you explicitly
deleted with "rm": it also works with your (graphical) file manager, mail
user agent, etc...



SUSPENDING/RESUMING libtrash:
----------------------------

Should you need to temporarily disable libtrash, you do so by running the
command

unset LD_PRELOAD

When you are done, libtrash can be reactivated by typing:

export LD_PRELOAD=path_of_symlink_to_libtrash

You might make these operations simpler by appending the following two lines
to the init file you used in step 5) above (if you are using Bash as your
shell):

alias trash_on="export LD_PRELOAD=path_of_symlink_to_libtrash"
alias trash_off="unset LD_PRELOAD"

After doing so, you can enable/disable libtrash by typing 

trash_on

or

trash_off

at the prompt.



CONTACT:
-------

This library was written by me, Manuel Arriaga. Feel free to contact me at
m.arriaga@ip.pt with questions, suggestions or bug reports.



CREDITS:
-------

- Avery Pennarun (apenwarr@foxnet.net), whose "freestyle-concept"
  tarball showed me how to intercept system calls and write a 
  suitable Makefile.