== What is vsipreload? ==

vsipreload is a library included with gdal which can be used to extend [[UserDocs/ReadInZip]] functionality to non-VSI-aware programs.

It works by using the dynamic linker's `LD_PRELOAD` system to override certain libc function calls with GDAL equivalents.

vsipreload currently only works on Linux.


== Building vsipreload ==

1. Build GDAL configured with `--with-pic`
2. Build the VSIPreload library:
  {{{
    g++ -Wl,-soname,libgdal_vsipreload.so.1 -Wall -fPIC \
      port/vsipreload.cpp \
      -shared -o libgdal_vsipreload.so.1 -Iport -L. -L.libs \
      -Wl,-Bstatic -lgdal \
      -Wl,-Bdynamic -ldl -lpthread -lcurl
}}}

Some notes: 

1. statically linked `-lgdal`. This means using `LD_PRELOAD` loads a fairly minimal symbol set, so conflicting symbols with libraries loaded later aren't a problem. Otherwise you may run into problems with conflicting symbols from the various GDAL dependencies. An example is the ESRI FileGDB API, which exports a lot of libxml symbols, and when preloaded it may cause segfaults in other code that uses libxml symbols.

2. (1) requires libgdal to be configured `--with-pic`, otherwise the static linking doesn't work.

3. debhelper/lintian seems to dislike libraries without sonames. You might be able to skip this step; YMMV.


== Using vsipreload ==

Just put `LD_PRELOAD` before your executable, and add the necessary `/vsi`... path parts to what you're doing:

{{{
$ LD_PRELOAD="./libgdal_vsipreload.so.1" ls /vsizip/vsicurl/http://svn.osgeo.org/gdal/trunk/autotest/ogr/data/poly.zip
poly.dbf  poly.PRJ  poly.shp  poly.shx
}}}