Device::Blkid::E2fsprogs version 0.12
=====================================

NOTE: This library only exposes the older e2fsprogs versions of libblkid ( numbered 1.xx.x)
and not the newer and preferred util-linux-ng versions ( v2.15 or better ). In almost
every case you would be advised to use Bastian Friedrich's util-linux-ng based Device::Blkid
module as the newer lib interface is (mostly) backward compatible with the old one. This
module would prove useful in any situation where for any reason you are limited on your
systems to a 1.xx.x libblkid version which is a part of the e2fsprogs package. Incidentally,
libblkid version numbering is based upon the version of either util-linux-ng or e2fsprogs of
which it was a part and as such, e2fsprogs based versions of the library were all numbered
v1.xx.x whereas util-linux-ng versions are numbered as v2.15 or better which was the version
of util-linux-ng in which it was added to that package. So just to be clear, when in doubt
you are advised to grab Bastian's newer util-linux-ng based libblkid interface module unless
you have some specific reason as to why you can't, perhaps something similar to what led me
to write this version.

This version has been implemented somewhat differently than Bastian's util-linux-ng build
of the library. He opted to keep much of his logic and processing in XSUB, mine is done
mostly in C; I have only used XSUB for my straight glue, everything else I kept in C. This is
not to be taken as any opinion of statement on PerlXS/XSUB, its merely a reflection of my own
background and tastes.

This package provides a Perl interface to the e2fsprogs-based versions of libblkid. It does not
support the larger and more robust API which has been added and integrated into the libblkid
library since its inclusion in the util-linux-ng package. That said, the libblkid which now
ships with util-linux-ng is reportedly backward compatible with client code dependant upon the
older, original library which would mean that this module should work with it, albeit with the
more limited selection of API calls. Please see the preceding note for additional details.

Libblkid provides a means of identifying block devices as to their content (such as filesystems)
as well as allowing for the extraction of additional information such as filesystem labels,
volume labels, serial numbers, device numbers, unique identifiers, etc. The libblkid library
maintains a mapping of all of this composite information and maintains its association with
a given block device on the system. Libblkid is becoming more commonly seen in modern linux
distributions in places such as configuration files and other such places where hard coded
device names were once used.

In addition to providing for low level probing of block devices for this information, the
library maintains an on disk cache file of this data. It is by way of the cache file that
unpriviledged users are able to access this information via a variety of library calls. Use of
the cache file as opposed to direct, low level probing of the hardware is recommended whenever
possible and feasible.

Recognizing that this is a Perl module, I have tried to provide a more 'Perlish' interface
where possible rather than merely map Perl subs to C functions. Most library functions return
an undef on failure and a number of calls return hash types.

Please read the README file in the package archive for instructions should you encounter any
problems while using this software package, as well as for instructions on building a debug
version.

It is worth noting that between versions 1.33 and 1.41.4, the entire period which libblkid
was shipping as a part of the e2fsprogs package, the number of calls present in the API
expanded from the 17 in the original release of the library back in 2003 to 24 when it was
migrated over to the util-linux-ng package in early 2009. This module supports all 24 calls
from the most recent iteration of this run. I will, in an upcoming version of this module,
provide a means for configuring this package for a target release of libblkid by way of the
in package Makefile.PL, but for now it supports the entire breadth of calls.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

Perl 5.10.0

This module also requires these other modules and libraries:

  e2fsprogs (pre v1.44)

DEBUGGING and REPORTING A BUG

If you have any problems with the functioning of this library, please contact me at my CPAN
address at mroz@cpan.org. Please be sure and include a list of packages installed on your system
or at least the exact version of e2fsprogs which you have installed. Also, please build and
install a DEBU build of this library as detailed below, execute the application which is using
this package and failing, and send me the verbose debugging output from the DEBUG build of this
package.

Should you wish to build a debug build of this library, please edit the Makefile.PL file and
set the __DEBUG DEFINE flag as is shown in the file. After setting, rebuild the library as per
The INSTALLATION instructions above. The debug build will produce much more verbose and chatty
output to STDOUT detailing what is talking place in the underlying C codes. Please be sure and
include all of this verbose output along with any problems you are having with this package. If
you find any problems with this package and wish to submit a patch, please send the unified diff
to my CPAN address including full patch instructions as well as a description of what issue or
bug you have found and addressed. Please patch as per recommended best practices found in the
patch(1) man page, under "NOTES FOR PATCH SENDERS".
  
COPYRIGHT AND LICENCE

Copyright (C) 2010 by Raymond Mroz

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.

THANKS

Thanks to Friedrich for inspiration, especially your POD; its saved me hours of just pounding
documenting calls in straight C into the lib.  Thanks.

BUGS

No known bugs at this time. That said, this module is largely written in C and does contain
a number of memory allocations. While these allocations are done inside of the libblkid itself,
I do make every attempt to free the memory explicitly when I am done with it. That said, leaks
are possible. Report any issues as is detailed above.
