NAME
    Sys::Filesystem - Retrieve list of filesystems and their properties

SYNOPSIS
        use strict;
        use Sys::Filesystem ();
    
        # Method 1
        my $fs = Sys::Filesystem->new();
        my @filesystems = $fs->filesystems();
        for (@filesystems)
        {
            printf("%s is a %s filesystem mounted on %s\n",
                              $fs->mount_point($_),
                              $fs->format($_),
                              $fs->device($_)
                       );
        }
    
        # Method 2
        my $weird_fs = Sys::Filesystem->new(
                              fstab => '/etc/weird/vfstab.conf',
                              mtab  => '/etc/active_mounts',
                              xtab  => '/etc/nfs/mounts'
                        );
        my @weird_filesystems = $weird_fs->filesystems();
    
        # Method 3 (nice but naughty)
        my @filesystems = Sys::Filesystem->filesystems();

DESCRIPTION
    Sys::Filesystem is intended to be a portable interface to list and query
    filesystem names and their properties. At the time of writing there were
    only Solaris and Win32 modules available on CPAN to perform this kind of
    operation. This module hopes to provide a consistent API to list all,
    mounted, unmounted and special filesystems on a system, and query as
    many properties as possible with common aliases wherever possible.

INHERITANCE
      Sys::Filesystem
      ISA UNIVERSAL

METHODS
    new Creates a new Sys::Filesystem object. "new" accepts following
        optional key value pairs to help or force where mount information is
        gathered from. These values are not otherwise defaulted by the main
        Sys::Filesystem object, but left to the platform specific helper
        modules to determine as an exercise of common sense.

        canondev
            Specify whether device path's shall be resolved when they're a
            symbolic link.

            $Sys::Filesystem::CANONDEV is used when no key "canondev" is
            passed.

        fstab
            Specify the full path and filename of the filesystem table (or
            fstab for short). Not all platforms have such a file and so this
            option may be ignored on some systems.

            $Sys::Filesystem::FSTAB is used when no key "fstab" is passed.

        mtab
            Specify the full path and filename of the mounted filesystem
            table (or mtab for short). Not all platforms have such a file
            and so this option may be ignored on some systems.

            $Sys::Filesystem::MTAB is used when no key "mtab" is passed.

        xtab
            DEPRECIATED Specify the full path and filename of the mounted
            NFS filesystem table (or xtab for short). This is usually only
            pertinant to Unix bases systems. Not all helper modules will
            query NFS mounts as a separate exercise, and therefore this
            option may be ignored on some systems.

            None of the OS plugins use that tunable (anymore?), so it now a
            warning is raised when it's used. The entire support will be
            removed not before 2015. Once that happened, using "xtab" will
            raise an exception.

        aliases
            Overrides internal aliasing table used to match queries against
            OS plugin. This should be used only when dealing with closed
            source platform helper module(s).

    supported
        Returns true if the operating system is supported by
        Sys::Filesystem. Unsupported operating systems may get less
        information, e.g. the mount state couldn't determined or which file
        system type is special ins't known.

  Listing Filesystems
    filesystems()
        Returns a list of all filesystem. May accept an optional list of key
        pair values in order to filter/restrict the results which are
        returned. The restrictions are evaluated to match as much as
        possible, so asking for regular and special file system (or mounted
        and special file systems), you'll get all.

        For better understanding, please imagine the parameters like:

          @fslist = $fs->filesystems( mounted => 1, special => 1 );
          # results similar as
          SELECT mountpoint FROM filesystems WHERE mounted = 1 OR special = 1

        If you need other selection choices, please take a look at DBD::Sys.

        Valid values are as follows:

        device => "string"
            Returns only filesystems that are mounted using the device of
            "string". For example:

                my $fdd_filesytem = Sys::Filesystem->filesystems(device => "/dev/fd0");

        mounted => 1
            Returns only filesystems which can be confirmed as actively
            mounted. (Filesystems which are mounted).

            The mounted_filesystems() method is an alias for this syntax.

        unmounted => 1
            Returns only filesystems which cannot be confirmed as actively
            mounted. (Filesystems which are not mounted).

            The unmounted_filesystems() method is an alias for this syntax.

        special => 1
            Returns only filesystems which are regarded as special in some
            way. A filesystem is marked as special by the operating specific
            helper module. For example, a tmpfs type filesystem on one
            operating system might be regarded as a special filesystem, but
            not on others. Consult the documentation of the operating system
            specific helper module for further information about your
            system. (Sys::Filesystem::Linux for Linux or
            Sys::Filesystem::Solaris for Solaris etc).

            This parameter is mutually exclusive to "regular".

            The special_filesystems() method is an alias for this syntax.

        regular => 1
            Returns only fileystems which are not regarded as special.
            (Normal filesystems).

            This parameter is mutually exclusive to "special".

            The regular_filesystems() method is an alias for this syntax.

    mounted_filesystems()
        Returns a list of all filesystems which can be verified as currently
        being mounted.

    unmounted_filesystems()
        Returns a list of all filesystems which cannot be verified as
        currently being mounted.

    special_filesystems()
        Returns a list of all fileystems which are considered special. This
        will usually contain meta and swap partitions like /proc and
        /dev/shm on Linux.

    regular_filesystems()
        Returns a list of all filesystems which are not considered to be
        special.

  Filesystem Properties
    Available filesystem properties and their names vary wildly between
    platforms. Common aliases have been provided wherever possible. You
    should check the documentation of the specific platform helper module to
    list all of the properties which are available for that platform. For
    example, read the Sys::Filesystem::Linux documentation for a list of all
    filesystem properties available to query under Linux.

    mount_point() or filesystem()
        Returns the friendly name of the filesystem. This will usually be
        the same name as appears in the list returned by the filesystems()
        method.

    mounted()
        Returns boolean true if the filesystem is mounted.

    label()
        Returns the fileystem label.

        This functionality may need to be retrofitted to some original OS
        specific helper modules as of Sys::Filesystem 1.12.

    volume()
        Returns the volume that the filesystem belongs to or is mounted on.

        This functionality may need to be retrofitted to some original OS
        specific helper modules as of Sys::Filesystem 1.12.

    device()
        Returns the physical device that the filesystem is connected to.

    special()
        Returns boolean true if the filesystem type is considered "special".

    type() or format()
        Returns the type of filesystem format. fat32, ntfs, ufs, hpfs, ext3,
        xfs etc.

    options()
        Returns the options that the filesystem was mounted with. This may
        commonly contain information such as read-write, user and group
        settings and permissions.

    mount_order()
        Returns the order in which this filesystem should be mounted on
        boot.

    check_order()
        Returns the order in which this filesystem should be consistency
        checked on boot.

    check_frequency()
        Returns how often this filesystem is checked for consistency.

OS SPECIFIC HELPER MODULES
  Dummy
    The Dummy module is there to provide a default failover result to the
    main Sys::Filesystem module if no suitable platform specific module can
    be found or successfully loaded. This is the last module to be tried, in
    order of platform, Unix (if not on Win32), and then Dummy.

  Unix
    The Unix module is intended to provide a "best guess" failover result to
    the main Sys::Filesystem module if no suitable platform specific module
    can be found, and the platform is not 'MSWin32'.

    This module requires additional work to improve it's guestimation
    abilities.

  Darwin
    First written by Christian Renz <[email protected]>.

  Win32
    Provides "mount_point" and "device" of mounted filesystems on Windows.

  AIX
    Please be aware that the AIX /etc/filesystems file has both a "type" and
    "vfs" field. The "type" field should not be confused with the filesystem
    format/type (that is stored in the "vfs" field). You may wish to use the
    "format" field when querying for filesystem types, since it is aliased
    to be more reliable accross different platforms.

  Other
    Linux, Solaris, Cygwin, FreeBSD, NetBSD, HP-UX.

  OS Identifiers
    The following list is taken from perlport. Please refer to the original
    source for the most up to date version. This information should help
    anyone who wishes to write a helper module for a new platform. Modules
    should have the same name as ^O in title caps. Thus 'openbsd' becomes
    'Openbsd.pm'.

REQUIREMENTS
    Sys::Filesystem requires Perl >= 5.6 to run.

TODO
    Add support for Tru64, MidnightBSD, Haiku, Minix, DragonflyBSD and
    OpenBSD. Please contact me if you would like to provide code for these
    operating systems.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Sys::Filesystem

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Filesystem>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Sys-Filesystem>

    *   CPAN Ratings

        <http://cpanratings.perl.org/s/Sys-Filesystem>

    *   Search CPAN

        <http://search.cpan.org/dist/Sys-Filesystem/>

SEE ALSO
    perlport, Solaris::DeviceTree, Win32::DriveInfo

VERSION
    $Id$

AUTHOR
    Nicola Worthington <[email protected]> - <http://perlgirl.org.uk>

    Jens Rehsack <[email protected]> - <http://www.rehsack.de/>

ACKNOWLEDGEMENTS
    See CREDITS in the distribution tarball.

COPYRIGHT
    Copyright 2004,2005,2006 Nicola Worthington.

    Copyright 2008-2014 Jens Rehsack.

    This software is licensed under The Apache Software License, Version
    2.0.

    <http://www.apache.org/licenses/LICENSE-2.0>