Shapefile C Library V1.2

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).

Copyright

The source for the Shapefile C Library is (c) 1998 Frank Warmerdam, and released under the following conditions. The intent is that anyone can do anything with the code, but that I do not assume any liability, nor express any warranty for this code.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Manifest

shapelib.html: This file - general documentation on the Shapefile C Library.
shp_api.html: Documentation for the API for accessing the .shp/.shx files.
dbf_api.html: Documentation for the API for accessing the .dbf attribute files.
shpopen.c: C code for access to .shp/.shx vertex files.
dbfopen.c: C code for access to .dbf attribute file.
shapefil.h: Include file defining all the services of dbfopen.c and shpopen.c.
dbfcreate.c: Simple example program for creating a new .dbf file.
dbfadd.c: Simple example program for adding a record to a .dbf file.
dbfdump.c: Simple example program for displaying the contents of a .dbf file.
shpcreate.c: Simple example program for creating a new .shp and .shx file.
shpadd.c: Simple example program for adding a shape to an existing shape file.
shpdump.c: Simple program for dumping all the vertices in a shapefile with an indicating of the parts.
shputils.c: Complex contributed program capable of clipping and appending shapefiles as well as a few other things. Type shputils after building to get a full usage message.
Makefile: A simple makefile to compile the library and example programs.
makeshape.sh: A simple script for running some of the example programs.
shptest.c: A simple test harnass to generate each of the supported types of shapefiles.
stream1.sh - A test script, which should produce stream1.out. Note this will only work if you have the example data downloaded.
stream1.out: Expected output of stream1.sh test script.
stream2.sh: A test script, which should produce stream2.out.
stream2.out: Expected output of stream2.sh test script.

What is a Shapefile?

If you don't know, you probably don't need this library. The Shapefile format is a new working and interchange format promulagated by ESRI (http://www.esri.com/) for simple vector data with attributes. It is apparently the only file format that can be edited in ARCView 2/3, and can also be exported and imported in Arc/Info.

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.

Release Notes

Release 1.2.5: SHPOpen() now forcably uses "rb" or "r+b" access string to avoid common mistakes on Windows.

Release 1.2.4: DBFOpen() will now automatically translate a .shp extension to .dbf for convenience. SHPOpen() will try datasets with lower and uppercase extension. DBFAddField() now returns the field number, not TRUE/FALSE.

Release 1.2.3: Disable writing measures to multi-patches as ArcView seems to puke on them (as reported by Monika Sester). Add white space trimming, and string/numeric attribute interchangability in DBF API as suggested by Steve Lime. Dbfdump was updated to include several reporting options.

Release 1.2.2: Added proper support for multipatch (reading and writing) - this release just for testing purposes.

Release 1.2 is mostly a rewrite of the .shp/.shx access API to account for ArcView 3.x 3D shapes, and to encapsulate the shapes in a structure. Existing code using the shapefile library will require substantial changes to use release 1.2.

Release V1.1 has been built on a number of platforms, and used by a number of people successfully. V1.1 is the first release with the xBase API documentation.

Maintainer

This library is maintained by me (Frank Warmerdam) on my own time. Please send me bug patches and suggestions for the library. Email can be sent to warmerda@home.com.

The current status of the Shapelib code can be found somewhere off my home page at http://members.home.com/warmerda.

The shputils.c module was contributed by Bill Miller (NC-DOT) who can be reached at bmiller@doh.dot.state.nc.us. I had to modify it substantially to work with the 1.2 API, and I am not sure that it works as well as it did when it was originally provided by Bill.

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.

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.