This is vitually straight out of the docs. Having read the ten lines of synopsis you have to call it like this which as you see performs as desired. The issue is that the df() method need to be called (it calls df(1) and caches the results) so that most of the other methods have data to work with. When reading those docs substitute Filesys::DiskFree->method() with $handle->method() and you should have no issues:

[root@devel3 root]# cat diskfree.pl
#!/usr/bin/perl

use Filesys::DiskFree;

$handle = new Filesys::DiskFree;
$handle->df();
my $device = $ARGV[0] || "/";
print "The $device device is ".$handle->device($device)."\n";
print "It has ".$handle->avail($device)." bytes available\n";
print "It has ".$handle->total($device)." bytes total\n";
print "It has ".$handle->used($device)." bytes used\n";

[root@devel3 root]# ./diskfree.pl
The / device is /dev/sda3
It has 79425527808 bytes available
It has 142137049088 bytes total
It has 55491371008 bytes used

[root@devel3 root]# ./diskfree.pl /boot
The /boot device is /dev/sda1
It has 31190016 bytes available
It has 47755264 bytes total
It has 14099456 bytes used

[root@devel3 root]# ./diskfree.pl /dev/sda1
The /dev/sda1 device is /dev/sda1
It has 31190016 bytes available
It has 47755264 bytes total
It has 14099456 bytes used
[root@devel3 root]#
[download]