Sys::Filesystem(3pm)

📦 version 1.408, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🦋 Sys::Filesystem 🦋

okay so you know how Sys::Filesystem(3pm) lives in the User Contributed Perl Documentation corner of your friendly neighbourhood man pages? yeah. that's this. it's giving "let me tell you everything about every filesystem on your box" and honestly? we're obsessed. 💖

✨ NAME ✨

Sys::Filesystem — bestie, it retrieves the list of filesystems and all their lil properties. that's the whole job. 💅

🌸 SYNOPSIS 🌸

like, here's how you'd actually use it. three whole methods, pick your fighter:

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();

Method 3 is literally labeled "nice but naughty" in the source and you KNOW that's the one everybody runs first. 🙈

💜 DESCRIPTION 💜

so Sys::Filesystem is meant to be a portable interface for listing and querying filesystem names and their properties. at the time of writing, there were only Solaris and Win32 modules on CPAN doing this kind of thing, which is, like, so limiting.

this module hopes (it's a hopeful lil module 🫶) to hand you a consistent API so you can list all, mounted, unmounted and special filesystems on a system, and query as many properties as possible — with common aliases wherever possible. consistency is the vibe. ✨

👑 INHERITANCE 👑

Sys::Filesystem
ISA UNIVERSAL

no cap, that's the whole ancestry chart. UNIVERSAL is everybody's grandparent. periodt.

🎀 METHODS 🎀

new

creates a brand new Sys::Filesystem object. slay. new accepts the following optional key/value pairs to help out — or straight up force — where mount info gets gathered from.

heads up bestie: these values are not otherwise defaulted by the main Sys::Filesystem object. they're left to the platform-specific helper modules to figure out as an exercise of common sense. so like, the vibes are delegated. 😭
  • canondev — specify whether device paths shall be resolved when they're a symbolic link. when no key canondev is passed, $Sys::Filesystem::CANONDEV is used. 💫
  • fstab — specify the full path and filename of the filesystem table (or fstab for short). not all platforms have such a file, so this option may be ignored on some systems. when no key fstab is passed, $Sys::Filesystem::FSTAB is used. 🗂️
  • mtab — specify the full path and filename of the mounted filesystem table (or mtab for short). not all platforms have such a file, so this option may be ignored on some systems. when no key mtab is passed, $Sys::Filesystem::MTAB is used. 📌
  • xtab — DEPRECIATED. specify the full path and filename of the mounted NFS filesystem table (or xtab for short). this is usually only pertinent to Unix-based systems. not all helper modules will query NFS mounts as a separate exercise, and therefore this option may be ignored on some systems.
🚨 okay this is important: none of the OS plugins use that tunable (anymore?), so now a warning is raised when it's used. the entire support will be removed not before 2015. once that has happened, using xtab will raise an exception. so like, it's on life support. rip bozo. 💀
  • aliases — overrides the internal aliasing table used to match queries against the OS plugin. this should be used only when dealing with closed source platform helper module(s). you've been warned, don't be messy with it.

supported

returns true if the operating system is supported by Sys::Filesystem. unsupported operating systems may get less information — like, the mount state couldn't be determined, or which file system type is special isn't known. 😭 they're doing their best but the info just isn't there.

🦋 Listing Filesystems 🦋

filesystems()

returns a list of all filesystem. (yes, all filesystem, singular-ish, we don't gatekeep grammar here 💅)

may accept an optional list of key/value pairs to filter/restrict the results returned. and here's the cute part: the restrictions are evaluated to match as much as possible, so if you ask for regular and special file system — or mounted and special file systems — you'll get all of them. it's inclusive. it's an ally. 🌈

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. pick a lane bestie, you can't have both.

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. they're in their off-duty era. 💤

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. just vibing. 🌸

💅 Filesystem Properties 💅

available filesystem properties and their names vary wildly between platforms. common aliases have been provided wherever possible, because we care. 🫶

you should check the documentation of the specific platform helper module to list all of the properties available for that platform. for example, read the Sys::Filesystem::Linux documentation for a list of all filesystem properties available to query under Linux. iykyk. 📚

  • 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. so like, check before you @ me. 🙈
  • volume() — returns the volume that the filesystem belongs to or is mounted on.
same disclaimer bestie: 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. the whole alphabet soup. 🍜
  • 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. 1️⃣2️⃣3️⃣
  • 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. it's the last module to be tried, in order of platform, Unix (if not on Win32), and then Dummy. it's the backup dancer. 💃

🌸 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. it's doing its best okay 😭

🐚 Darwin

first written by Christian Renz <crenz@web42.com>. give credit where credit is due. 🫶

🪟 Win32

provides mount_point and device of mounted filesystems on Windows. two properties, but they're the useful ones. 💅

💜 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. learn from other people's confusion, bestie.

🦋 Other

Linux, Solaris, Cygwin, FreeBSD, NetBSD, HP-UX. the whole squad. 🔥

🎀 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. ancient. vintage. iconic. 👑

🔥 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. volunteering is very main character energy, just saying. 💖

🫶 SUPPORT 🫶

you can find documentation for this module with the perldoc command.

perldoc Sys::Filesystem

you can also look for information at:

👀 SEE ALSO 👀

perlport, Solaris::DeviceTree, Win32::DriveInfo, Sys::Filesystem::MountPoint

💜 AUTHOR 💜

Nicola Worthington <nicolaw@cpan.org> - <http://perlgirl.org.uk>

Jens Rehsack <rehsack@cpan.org> - <http://www.rehsack.de/>

legends, both of them. 🫡

🎀 ACKNOWLEDGEMENTS 🎀

see CREDITS in the distribution tarball. ✨

okay so legal era, bestie — gotta give credit where credit is due 💅

  • Copyright 2004,2005,2006 — that's Nicola Worthington 🎀
  • Copyright 2008-2020 — and that's Jens Rehske 🦋

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

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

fr fr, if you're gonna use this, respect the license — it's the bare minimum and it's giving main character integrity 💖

and that's a wrap on the whole page, bestie 🫶 This one came to you from perl v5.30.3, dated 2020-10-24, filed under Sys::Filesystem(3pm) — go mount something responsibly, ily, bye 💅🌸

📦 where this page comes from