** Overview
   This is version 1.2 of the CMUCS dumpscan tools.  This package
   consists of two libraries and several utilities:

   - libxfiles is an extensible library for accessing file-like
     things.  It provides 64-bit-clean access to a variety of
     data streams, including files and AFS volume dump RPC's.
     Also included is a module for profiling file operations.

   - libdumpscan is a library for parsing and generating AFS volume
     dumps.  It provides a callback mechanism for custom processing
     of each dump component, support for printing some or all dump
     components, and detection and correction of dump file errors.
     It also provides a set of routines for generating dump files.

   - afsdump_scan is a general-purpose utility for scanning and
     repairing volume dumps.  It provides a command-line interface
     to the printing and repair options provided by the dumpscan
     library.

   - afsdump_dirlist is a utility which uses the dumpscan library
     to list the contents of an AFS directory file.

   - afsdump_extract is a tool for extracting the contents of a
     volume dump into a local filesystem.  It can extract files
     by pathname or vnode number.

   - afsdump_xsed is the beginnings of a tool for modifying the
     contents of a volume dump in a systematic way.

   - genrootafs is a tool which reads a CellServDB file and emits
     a volume dump suitable for use in creating a root.afs volume.
     It currently has issues with the stability of the vnode numbers
     and uniqifiers used, and so is not yet appropriate for use in
     a production environment.

   I originally wrote the dumpscan library to help understand a
   problem in our backup system that was causing restored volume
   dumps to be corrupted, and to attempt to repair those dumps.
   We eventually found the problem -- a device driver bug -- but
   the tools have lived on, and have proved to be useful on many
   occaisons since.

   We wrote these tools for ourselves, but in the spirit of sharing,
   we've decided to make them available to the community at large.
   We ask (but do not demand) that you do the same, and return any
   changes to us so that we can redistribute them in a future version.
   Please see the "Copyright" section for licensing details.


** Where to Get It
   The latest official distribution of these tools can be obtained
   from any of the following locations:

     /afs/grand.central.org/software/dumpscan
     http://grand.central.org/dl/software/dumpscan
     ftp://grand.central.org/pub/software/dumpscan


** Installation
   At present, there is no configure script or install target.
   This version builds out of the box on our Linux and Solaris systems,
   which have OpenAFS installed in /usr/local.  Other platforms or
   configurations may require editing the Makefile.


** Interface Stability
   The current command-line options and API's are substantially similar
   to those of the earliest versions of these tools, but are "unstable"
   in that I may add new options or make changes from time to time.  In
   general, it should work to recompile existing source code against new 
   versions of the library, but there may be minor issues.  I make no
   promises of ABI stability at this point; if you upgrade to a new
   version of the library, you must recompile.

   As a result of their age and the relative haste with which these tools
   were originally put together, the interfaces are all a bit clunky.
   At some point I will release a version 2.0 whose interfaces will likely
   be completely redesigned and incompatible with the existing ones.
   You have been warned.


** Copyright

   Copyright (c) 1998, 2001, 2003-2006 Carnegie Mellon University
   All Rights Reserved.
   
   Permission to use, copy, modify and distribute this software and its
   documentation is hereby granted, provided that both the copyright
   notice and this permission notice appear in all copies of the
   software, derivative works or modified versions, and any portions
   thereof, and that both notices appear in supporting documentation.
  
   CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
   CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
   ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  
   Carnegie Mellon requests users of this software to return to
  
    Software Distribution Coordinator  or  Software_Distribution@CS.CMU.EDU
    School of Computer Science
    Carnegie Mellon University
    Pittsburgh PA 15213-3890
  
   any improvements or extensions that they make and grant Carnegie Mellon
   the rights to redistribute these changes.