NAME

Device::Blkid - Interface to libblkid

VERSION

Version 0.9

SYNOPSIS

WARNING: This module requires libblkid 2.16 or newer, i.e. a version that ships with util-linux-ng (in contrast to older library versions, which were part of e2fsprogs).

Device::Blkid closely resembles the native interface of libblkid. All functions provided by libblkid are available from Perl as well. Most functions work exactly the same way, although a few have been slightly modified to behave a little more "Perlish".

The most common way of using libblkid will be requesting a device (name) referring to a device with a given attribute (e.g., "return device name for LABEL=foo"), or you want all tags of a certain device.

In most cases, it is sensible to use the blkid cache; "undef" will work in most cases.

 use Device::Blkid qw(:funcs);

 my $cache = blkid_get_cache();

 # Request (first) device with given attribute
 my $devname = blkid_get_devname($cache, 'LABEL', 'foo');
 print("Device $devname has label foo\n");

 # Request attributes of given device
 my $label = blkid_get_tag_value($cache, 'LABEL', '/dev/sda1');

 # Request all attributes of a given device
 use Data::Dumper;
 my $device = blkid_get_dev($cache, '/dev/sda1', 0);
 print("Dump of device attributes: " . Dumper($device));

Most devices contain a label, a UUID, and a type.

Please note that functions in section "probe.c" are currently untested and undocumented.

EXPORT

No functions or variables are exported per default. All functions and constants listed below can be imported explicitly, though.

An export tag :funcs exports all functionsprovided by this module; :consts exports all known constants.

CONSTANTS

This module provides a number of constants that are also contained in the blkid.h header:

BLKID_DEV_
- BLKID_DEV_FIND
- BLKID_DEV_CREATE
- BLKID_DEV_VERIFY
- BLKID_DEV_NORMAL
BLKID_PROBREQ_
- BLKID_PROBREQ_LABEL
- BLKID_PROBREQ_LABELRAW
- BLKID_PROBREQ_UUID
- BLKID_PROBREQ_UUIDRAW
- BLKID_PROBREQ_TYPE
- BLKID_PROBREQ_SECTYPE
- BLKID_PROBREQ_USAGE
- BLKID_PROBREQ_VERSION
BLKID_USAGE_
- BLKID_USAGE_FILESYSTEM
- BLKID_USAGE_RAID
- BLKID_USAGE_CRYPTO
- BLKID_USAGE_OTHER
BLKID_FLTR_
- BLKID_FLTR_NOTIN
- BLKID_FLTR_ONLYIN

You may either access these constants in a fully qualified way (e.g., Device::Blkid::BLKID_DEV_FIND), by importing single constants, or by importing the :consts token. See "EXPORT" section.

FUNCTIONS

The original libblkid functions are not split into categories; they are, however, listed per source file. This sequence is resembled here.

cache.c

Function `blkid_put_cache($cache)`

Writes the cache object referenced by $cache back to disk. $cache is invalidated by this call and MUST NOT be used afterwards.

Returns a true value on success, undef on failure.

Function `blkid_get_cache($filename)`

Reads the cache from given file, or from the default cache file if $filename is not defined.

Returns a Device::Blkid::Cache object (which is only usable as argument to other functions) on success, undef on failure.

Function `blkid_gc_cache($cache)`

Runs a garbage collection on given cache object.

Returns a true value on success, undef on failure (cache invalid).

dev.c

The following functions provide iterations over multiple devices: either all, or a subset filtered by a search. Get an iterator with "blkid_dev_iterate_begin", optionally set a search filter with "blkid_dev_set_search", fetch the next object with "blkid_dev_next", and finally destroy the iterator with "blkid_dev_iterate_end".

While you are encouraged to call "blkid_dev_iterate_end", the class Device::Blkid::DevIterate will automaticall destroy the associated iterator when it is removed from memory (i.e., when it is no longer referenced).

Function `blkid_dev_devname($dev)`

Returns the device name associated with a Device::Blkid::Device object, or undef uppon failure.

Function `blkid_dev_iterate_begin($cache)`

Returns an iterator of type Device::Blkid::DevIterate to iterate over multiple devices (or undef uppon failure).

A cache object is mandatory for this function.

Function `blkid_dev_set_search($iter, $search_type, $search_value)`

Restricts objects returned by iterators to given search; e.g., filter for ext3 file systems with this:

 blkid_dev_set_search($iter, 'TYPE', 'ext3');

Function `blkid_dev_next($iterate)`

Returns the next device (as a Device::Blkid::Device object) in this iteration, or undef, when the end of the list is reached (or another problem was encountered).

Function `blkid_dev_iterate_end($iterate)`

Returns the $iterate object. Does not need to be called (auto-destroyed by perl).

devno.c

Function `blkid_devno_to_devname(major, minor|devno)`

Returns a device name for any given device number. If passed two arguments, the device number (devno) will be major << 8 + minor.

 printf("Device 8, 1 is %s, device 2049 is %s as well\n",
        blkid_devno_to_devname(8,1),
        blkid_devno_to_devname(2049));

Undef is returned for non-existing devices:

 if (!blkid_devno_to_devname(0, 1)) {
        print("No Device 0, 1 found\n");
 }

devname.c

Function `blkid_probe_all($cache)`

Probes all devices in cache. Returns a true value on success, false on failure.

Function `blkid_probe_all_new($cache)`

Probes new devices to cache. Returns a true value on success, false on failure.

Function `blkid_get_dev($cache, $devname, $flags)`

Returns a Device::Blkid::Device object referring the given device name (or undef uppon failure).

Flag BLKID_DEV_CREATE may be given in the flags argument to generate a new cache entry.

getsize.c

Function `blkid_get_dev_size($fd)`

Returns the size of the given device. Please note that the device is passed by a file descriptor (not a Perl file handle!). See POSIX::open for more information.

verify.c

Function `blkid_verify($cache, $dev)`

Verify that the data in $dev is consistent with what is on the actual block device (using the devname field only). Normally this will be called when finding items in the cache, but for long running processes is also desirable to revalidate an item before use.

$dev is expected to be a Device::Blkid::Device object (as returned e.g. by blkid_get_dev), not a device name.

read.c

read.c does not contain any user-accessible functions.

resolve.c

Function `blkid_get_tag_value($cache, $tagname, $devname)`

Returns the requested tag for a device (or false uppon failure), e.g.:

 printf("Type of my sda1 is %s\n",
        blkid_get_tag_value($cache, 'TYPE', '/dev/sda1'));

Function `blkid_get_devname($cache, $token, $value)`

Return the first device with the given tag/value pair, e.g.

 printf("Device with label foo is %s\n",
        blkid_get_devname($cache, 'LABEL', 'foo'));
 printf("Identical request with token as name=value: %s\n",
        blkid_get_devname($cache, 'LABEL=foo'));

tag.c

The three following functions blkid_tag_iterate_begin($dev), blkid_tag_next($iterate), and blkid_tag_iterate_end iterate over the attributes of a requested device (Device::Blkid::Device, not device name).

Object method Device::Blkid::Device::toHash() provides a much simpler way to access all attributes.

Function `blkid_tag_iterate_begin($dev)`

Fetches an iterator object for the given device.

Function `blkid_tag_next($iterate)`

Returns the next attribute set for the device as a hash of this structure:

 $VAR1 = {
        type    => 'LABEL',
        value   => 'myLabel',
 };

Returns undef, when there are no more entries (or uppon other failures).

Function `blkid_tag_iterate_end($iterate)`

Frees data associated with this object. Auto-destruction is implemented, when the iterator object is freed, i.e. you do not have to call this function manually.

Function `blkid_dev_has_tag($dev, $type, $value)`

Checks whether the given device has the attribute $type=$value set; returns true in that case, false otherwise.

 if (blkid_dev_has_tag($dev, 'LABEL', 'foo')) {
        print("Yes, your device is labeled foo\n");
 }

Function `blkid_find_dev_with_tag($cache, $type, $value)`

Finds (and returns) the first device with the given type/value pair, and returns it as an object of type Device::Blkid::Device.

Function `blkid_parse_tag_string($token)`

For a given string "foo=bar", returns a hash { type = 'foo', value => 'bar'}>.

Returns undef if the string is not parsable.

version.c

Function `blkid_parse_version_string($ver_string)`

Returns an integer representation of a version string. Internal format in libblkid.

Function `blkid_get_library_version($ver_string, $date_string)`

Returns a hash containing basic information about the installed version of libblkid:

 $VAR1 = {
        int     => 2160,
        ver     => '2.16.0',
        date    => '10-Feb-2009',
 };

encode.c

Function `blkid_encode_string($str)`

Encode all potentially unsafe characters of a string to the corresponding hex value prefixed by '\x'.

Returns that string on success, or undef on failure. Other than the libblkid version, no partial strings are returned.

Function `blkid_safe_string($str)`

Allows plain ascii, hex-escaping and valid utf8. Replaces all whitespaces with '_'.

Returns that string on success, or undef on failure.

evaluate.c

Function `blkid_send_uevent($devname, $action)`

Sends the given action as a uevent to the udev entry of the respective device.

Returns a true value on success, a false value on failure. Please note that "success" does not necessarily mean that the uevent was triggered successfully.

Function `blkid_evaluate_tag($token, $value, $cache)`

Returns the device name where the given token=value pair holds, or undef on failure.

$cache argument may be ommited.

probe.c

Most functions in this section have NOT been tested well and currently remain undocumented. Please see libblkid for further information.

Function `blkid_known_fstype($fstype)`

Checks whether fs type $fstype is known by the installed version of libblkid. Returns true in that case, false otherwise.