Device::Blkid::E2fsprogs version 0.22 ===================================== 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. E2FSPROGS-LIBBLKID VERSION HISTORY Libblkid first appeared in version 1.33 of the e2fsprogs package back in 2003. The initial iteration of the library exposed 17 function calls as part of its API. When libblkid stopped shipping with the e2fsprogs package, the API call count was at 25 functions which had been a part of the API since version 1.40 of e2fsprogs. The API history is as follows: v1.33 - 17 calls v1.34 - 18 calls v1.36 - 21 calls v1.38 - 24 calls v1.40 - 25 calls In version 1.36 of libblkid two functions appeared which returned version information about the library, those were: int blkid_parse_version_string(const char *ver_string); int blkid_get_library_version(const char **ver_string, const char **date_string); INSTALLATION This module uses an optional dynamic libblkid version detection mechanism to try and ascertain which version of libblkid is installed on the target system. It is optional and you are free to select the libblkid version manually as well. After running the standard, 'perl Makefile.PL', please follow the in screen prompts for installation details. Please see the following sample installation scenarios for further details. This first scenario demonstrates a sample configuration and installation using the dynamic libblkid library version detection. Begin by running the Makefile.PL program, answering in the affirmative, 'Y/y' when asked to try the dynamic version detection, as follows: $ perl Makefile.PL Running Makefile.PL to perform package configuration. Would you like to try dynamic libblkid version detection and configuration? Y/y or N/n: y Version 1.40 or better of libblkid detected. Building module for that version Checking if your kit is complete... Looks good Writing Makefile for Device::Blkid::E2fsprogs Here the dynamic version detection has successfully determined that version 1.40 or newer of libblkid is installed on the target system and has written a Makefile which will generate a matching module installation. Now that you have a Makefile which properly matches your version of libblkid, the remainder of the build/install process is standard: make make test make install This second scenario involves manual selection of a libblkid library version target and is initiated by replying in the negative to the first question about dynamic version detection: $ perl Makefile.PL Running Makefile.PL to perform package configuration. Would you like to try dynamic libblkid version detection and configuration? Y/y or N/n: n The default is to build a v1.33 compliant interface as it will work with all e2fsprogs-based versions of libblkid. Keep in mind that attempting to build a version target which is more recent than the version which you have installed will fail with linker errors. If you are not entirely certain which version which you have installed, accepting the default here (a 'Y/y' selection) is safest, however you may wish to try the dynamic version detection which should accurately determine versions 1.36 and newer. If the default v1.33 build target is acceptable to you, please answer 'Y/y', otherwise select one of the following version bundles from the list, or 'Q/q' to quit: 1. v1.36 (compliant with libblkid versions 1.36-1.37) 2. v1.38 (compliant with libblkid versions 1.38-1.39) 3. v1.40 (compliant with all libblkid versions better than 1.40) Enter selection (Y/y for default or option 1, 2, 3): 2 Checking if your kit is complete... Looks good Writing Makefile for Device::Blkid::E2fsprogs In this case the user has manually selected option 2, v1.38 of libblkid. This build target is compliant with versions 1.38 and 1.39 of the library and a corresponding Makefile has been generated which can now be run to build and install the target module. Again, this is done using the standard make, make test, make install method: make make test make install Finally, a third option is to edit the Makefile.PL directly for any custom requirements. Please see that file for further details as it has been well documented. ===== libblkid version detection ===== I have made use of a customized Devel::CheckLib module and Makefile.PL in an attempt to detect the version of libblkid currently installed on the target system and to then generate a PerlXS interface which directly targets and matches the API interface of that libblkid version. This process is expected to work on all versions of libblkid later than v1.35. Should you have any problems with this process, evident either in running the Makefile.PL or in running make on its resulting Makefile, please see the Makefile.PL as well as the E2fsprogs.xs file to troubleshoot. If you wish to report any problems with this version detection, please include any output from the installation process as well as a copy of your /usr/include/blkid/blkid.h file. DEPENDENCIES Perl 5.8.0 This module also requires these other modules and libraries: E2fsprogs v1.33-v1.41 * Note: In order to install this package on systems running a version of libblkid older than version 1.36, you will be required to manually edit the Makefile.PL, adding the proper define CFLAG(s) for gcc as well as determine which function calls are present in the API exposed by the version of your particular libblkid and either comment out or remove them from the E2fsprogs.xs file. Keep in mind that the libblkid funtions appear in two seperate sections of that file; in the top half, which is the C language section and at the bottom, the Perl XSUB section. 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 debug 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. There are two ways to produce a debug build of this module package. The first, and easiest, is to pass a debug DEFINE to the Makefile.PL file when configuring the package for installation. To install a DEBUG build in this way, type the following from the top level of this package: perl Makefile.PL DEFINE=-D__DEBUG make make test make install The second method is to edit the Makefile.PL file itself and to add the '-D__DEBUG' define to the DEFINE argument of the WriteMakefile method found in the file (see the comments inside the file for additional details. Should you run a DEBUG build of this package you will note a much higher level of verbosity in the output from the execution of the library. Please capture and submit any and all of this additional verbosity to me at my CPAN address making sure to include a complete description of the abhorrent behavior you have or are observing while using this package. Furthermore, 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 Bastian for all of is work on Device::Blkid, I was especially appreciative of your POD as libblkid itself is not terribly well documented. While I did make a large number of my own straight test calls in C against the library your documentation kept me in the right direction and saved me a load of time by allowing me to concentrate my efforst in the right place. 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.