What is AVFS?
------------

AVFS is a C library add-on, which enables all programs to look inside
gzip, tar, zip, ... files, without recompiling the programs or chaging
the kernel. At the moment it supports tar, zip, gzip, bzip2, and
partially rar files. More is to come!

AVFS is (C) under the GNU GPL (See the file COPYING) (Hopefully it
will be LGPL in the future)

How to install
--------------

IMPORTANT NOTE: 

For GLIBC based systems it is _NOT_ enough to get the source, compile
and install the shared library, because the system can contain libc-5
binaries which WILL CRASH if this library is loaded. So you can either
compile a libc-5 version as well (no idea how to do this), or install
the libc-5 library from the binary package.

If you've got the binary package for Linux, do the following:

- Check what type of libc your system uses by default, libc-5 or GLIBC.
  RedHat 5.x and some other newer distributions are GLIBC based, the
  rest is libc-5.

- Check and edit the respective install script (install-libc5 or
  install-glibc). Probably no adjustments are necessary. 

- Run the install script:

for a libc-5 system (NEVER run this on a GLIBC system).

   ./install-libc5

for a GLIBC system

   ./install-glibc

If you want to recompile this library, or statically link your program
with it, see the chapter 'How to compile'. 

How to use
----------

To enable AVFS support, set the environment variable LD_PRELOAD to
libavfs.so:

in C-shell type shells (csh, tcsh, ...)

  setenv LD_PRELOAD libavfs.so

in Bourne-shell type shells (sh, bash, ...)
  
  LD_PRELOAD=libavfs.so; export LD_PRELOAD

Now you'll have AVFS functionality in all programs started from this
shell. You can try it for example, by listing a tar archive:

  ls -l avfs-0.2.tgz:/
  ls -l avfs-0.2.tgz:/avfs-0.2/

If you now start a subshell, or an xterm, this shell itself will have
AVFS functionality, so filename completion also works, and you can
'cd' into a tarfile:

  tcsh
  cd avfs-0.2.tgz:/
  less avfs-0.2/README

Well, use it for whatever you want. In theory all programs should be
able to run and use these virtual files. If something doesn't work,
then check the section 'Common Problems'.

One thing that doesn't work is input and output redirection to/from
virtual files.

E.g. you can't do
        patch -p0 < patchfile.gz:

only
        cat patchfile.gz: | patch -p0

For the same reason 
        tar tvfz tarfile.tgz:/dir/second_tarfile.tgz

won't work, but
        tar tvf tarfile.tgz:/dir/second_tarfile.tgz:gz

should. (It does not in fact, due to the fact that 'tar' also
interprets the ':' character).

Format of an AVFS path
----------------------

As you've seen, the ':' magic character makes a virtual file or
directory from an ordinary file. Actually this is just a shorthand for
the full specification of an AVFS path:

  'tarfile.tgz:' is the same as 'tarfile.tgz:gz:tar'

Note, the short version will only work if the file-extension is
recognized (most are), but you can always tell exactly what should be
done with the file by using the second method.

The following file "handelers" are available now:

  :gz   - gunzip
  :bz2  - bunzip2
  :tar  - untar
  :zip  - unzip
  :rar  - unrar

Common problems
---------------

1) Can't access the virtual files

 There could be many causes of this, use your common sense. 
 One cause could be, that the AVFS library can't find the modules.
 Check that modules are installed in /usr/lib/avfs and have read and
 execute permissions.

2) Some programs crash (segfault) on startup

 If it's a GLIBC system, this maybe because the program you started is
 linked with a Libc-5 library (you can check with 'ldd'), and the
 system can't find a Libc-5 version of libavfs.so. To correct, make
 sure, that you have installed a libc-5 version of libavfs.so as well,
 and that both versions are found by ldconfig (run 'ldconfig -v').

OK, if you can't figure out the cause of the problem, than you
probably found a bug. Please read the section 'Reporting bugs'.

How to compile
--------------

At the moment AVFS can be compiled under the following systems:

- Intel-x86 Linux libc-5 
  (I have Linux 2.1.101 and libc-5.4.44, but I hope others work too)

- Intel-x86 Linux GLIBC-2 (or libc-6)
  (I tried it with Linux 2.0.32 and libc-2.0.5)

- Sparc Solaris 2.5.1

To compile, type 'make'. This will build the preloadable shared
library (libavfs.so), the modules (gz.so, tar.so ...) and a static
library (libavfs.o).

Warnings in 'realcall.c' are OK, but you may even have to tweak this
file and/or 'config.h' to make it compile.

The statically linked object-file is for you to link to your
programs. A program distributed this way will have AVFS functionality
even if the preloadable library is not available. To link it with your
program just add this object file to the list of '.o' files passed to
the linker. 

Porting to other systems
------------------------

This should not be too hard. You should check realcall.c and config.h,
and try to work out the things for your system. 

Writing new modules
-------------------

You want to write a handler module for XY? Great! Please contact me,
and I can give you some advice regarding this.

Reporting Bugs
--------------

If you found a bug, you should tell me the following information:

  - What system are you using.
  
  - On linux the C-library version (libc-5 or GLIBC).

  - WHEN does the problem occur? (at startup, or when you 
    access some virtual file, ...)

  - Which program(s) cause problems? What libraries these programs are
    linked with (check with 'ldd').

  - Check the file BUGS, to see if one of those might match your
    problem.

Please send Bug reports to the Email address at the end of this
documet. Thanks in advance for your help!

If you are familiar with programming and would like to be of BIG help,
you might try to find out exactly where the program crashes. You could
try to debug the offending program, or uncomment the '#define DEBUG'
line in switch.c and see what system calls are executed.

Credits
-------

David Hanak (dhanak@inf.bme.hu) has contibuted the "rar" and the
"archive" modules, and lots of ideas to AVFS.

The VFS in Midnight Commander, written by Jakub Jelinek and Miguel de
Icaza <miguel@nuclecu.unam.mx>, has greatly helped me write this
library, and will probably continue to do so in the future.

The tar file handler is largely based on the GNU tar source,
originally written by John Gilmore.

People, who sent me ideas or bug-reports:
  Jan Niehusmann <jan@gondor.com>
  Demon of the Known Universe <psycho@dodds.net>
  Duncan Pierce <cmrdrp@soc.staffs.ac.uk>
  Scott F. Johnston <scott@fleetingimage.com>

Where is the rest of this document
----------------------------------

This project is quite new, so it's not yet in existence.  Also if you
are (fairly) missing some other feature from AVFS see the file
TODO. If you have some other suggestions or if you want to help,
please contact me:

Miklos Szeredi <mszeredi@inf.bme.hu>

