# Shapefile C Library

## Purpose

The Shapefile C Library provides the ability to write simple C programs for reading, writing and updating (to a limited extent) ESRI Shapefiles, and the associated attribute file (.dbf).

## Supporting Information

- Shapefile API Docs
- DBF/xBase API Docs
- Shapefile Tools Docs
- Release Notes
- Shapelib File Manifest
- Shapelib Licensing Terms

## What is a Shapefile?

If you don't know, you probably don't need this library. The Shapefile format is a working and interchange format promulagated by ESRI for simple vector data with attributes.

An excellent white paper on the shapefile format is available from ESRI, but it is .pdf format, so you will need Adobe Acrobat to browse it.

The file format actually consists of three files.

    XXX.shp - holds the actual vertices.
    XXX.shx - hold index data pointing to the structures in the .shp file.
    XXX.dbf - holds the attributes in xBase (dBase) format.

## Download

Source code, and some other odds and ends can be downloaded from http://download.osgeo.org/shapelib.

Shapelib is available for anonymous CVS access:

      cvs -d :pserver:cvsanon@cvs.maptools.org:/cvs/maptools/cvsroot login
      Password: (hit enter)
      cvs -d :pserver:cvsanon@cvs.maptools.org:/cvs/maptools/cvsroot co shapelib

## Bugs, Maintainance and Support

This library is maintained by Frank Warmerdam. Please send me bug reports, patches and suggestions for the library via the maptools.org Bugzilla. Shapelib bugs can also be queried.

Shapelib is hosted at shapelib.maptools.org. A mailing list for discussion of how to use shapelib, and announcing new releases is available. To only find out about new releases of Shapelib select the "Subscribe to new releases" option from the link at Freshmeat.

## Credits

I didn't start this section anywhere near soon enough, so alot of earlier contributors to Shapelib are lost in pre-history.

- Bill Miller (NY-DOT) for shputils.c
- Carl Anderson for the contents of the contrib directory, and the "tuple" additions to dbfopen.c.
- Andrea Giacomelli for patches for dbfopen.c.
- Doug Matthews for portability improvements.
- Jan-Oliver Wagner for convincing me to make it available under LGPL, shared library support, and various other patches.
- Dennis Christopher (of Avenza) for testing and bug fixes.
- Miko Syrjä (of 3D-system Oy) for a record size bug fix.
- Steven Lime and Curtis Hill for help with NULL shapes.
- Jim Matthews for support of NULL attributes in dbf files.
- PCI Geomatics who let me release a modified version of their shapefile code in the beginning and who hosted shapelib for years.

## In Memorium

I would like to dedicate Shapelib to the memory of Sol Katz. While I never met him in person, his generous contributions to the GIS community took many forms, including free distribution of a variety of GIS translators with source. The fact that he used this Shapelib in some of his utilities, and thanked me was a great encouragement to me. I hope I can do his memory honour by trying to contribute in a similar fashion.

## Portability

The Shapefile C Library should port easily to 32bit systems with ANSI C compilers. It should work on 64 bit architectures (such as the DEC AXP).

Care should also be taken to pass the binary access flag into SHPOpen() and DBFOpen() when operating on systems with special text file translation such as MSDOS.

The shputils.c module is contributed, and may not take the same approach to portability as the rest of the package.

On Linux, and most unix systems it should be possible to build and install shapefile support as a shared library using the "lib" and "lib_install" targets of the Makefile. Note that this Makefile doesn't use autoconf mechanisms and will generally require some hand tailoring for your environment.

## Limitations

- You can't modify the vertices of existing structures (though you can update the attributes of existing structures, and create new structures).

- Not written in such a way as to be particularly fast. This is particularly true of the 1.2 API. For applications more concerned with speed it may be worth using the V1.1 API.

- Doesn't set the last access time properly in the .dbf files.

- There is no way to synchronize information to the file except to close it.

- Poor error checking and reporting.

- Not professionally supported (well it can be, if you want to pay).

- Some aspects of xBase files not supported, though I believe they are not used by ESRI.

- The application must keep the .dbf file in sync with the .shp/.shx files through appropriate use of the DBF and SHP APIs.

- No support for the undocumented .sbn/.sbx spatial index files.

## Other Shapefile Resources

- Shapefile Format Specifications (pdf)

- Xbase (.dbf) File Format Description.

- Language ID / Code Page mappings

- Shapelib is used within the multiformat OGR library. If you are looking for a high level C++ library with support for many geospatial vector formats you might want to check it out.

- Ari Jolma has produced an initial perl binding on top of shapelib, which can be found at CPAN as Geo::ShapeFile under the Geo module.

- Bernhard Herzog has produced python bindings for Shapelib with SWIG, available at http://ftp.intevation.de/users/bh/pyshapelib. A new version not using swig is available as part of Thuban.

- Delphi bindings for Shapelib courtesy of Alexander Weidauer.

- Miguel Filgueiras has implemented Tcl bindings for Shapelib as part of GPSMan.

- David Gancarz has implemented a Microsoft .NET wrapper for Shapelib. An example of using shapelib with VB6 is also icluded in the .NET wrapper project file.

- Andrey Hristov (php at hristov dot com) has developed a PHP extension based on Shapelib. It can be found in CVS at http://cvs.php.net/pecl/shp.

- Toyoda Eizi has developed Ruby bindings found at http://sourceforge.net/projects/ruby-shapelib.

- Davide Cesari has developed FORTRAN bindings that can be found at http://www.webalice.it/o.drofa/davide/shapelib-fortran.
- Jan-Oliver Wagner has implemented a commandline program (gen2shp) for producing shapefiles from Arc/Info Generate format ASCII files. He maintains a web page for his work.

- Tom Russo has implemented a shpcs2cs program, which reprojects shapefiles using arguments similar to the PROJ.4 cs2cs program including datum conversion. Use as an alternate to the contrib/shpproj which doesn't do datums. It is available at the bottom of Tom's Xastir Shapefile Resources page.

- Andrew Williamson's Useful Scripts and Stuff page for ArcView, which includes ShapeChecker.

- The University of Bonn sf4java project apparently includes Java classes for reading Shapefiles.

- The ShapeIO2 Visual Basic libraries may be of interest to those wanting VB access to Shapefiles. Also available locally.

- The ShapeFile Read/Write OCX is another option for Visual Basic programmers.

- Isovist Analyst is a sort-of-free isovist generating extension for ArcView using shapelib.

- shpdiff utility by Bryce Nesbitt.

- Aequometer: a program for MS Excel to calculate the area of polygons and export as shapefiles.