Stat::lsMode(3pm)

💖 Stat::lsMode 💖

okay bestie, welcome to Stat::lsMode — a Perl module from the User Contributed Perl Documentation collection that formats file modes exactly like the Unix ls -l command does. she's giving permission string realness and honestly? iconic. ✨

---

🌸 NAME 🌸

Stat::lsMode — format file modes like the ls -l command does 💅

---

✨ SYNOPSIS ✨

use Stat::lsMode;

$mode = (stat $file)[2];
$permissions = format_mode($mode);
# $permissions is now something like  `drwxr-xr-x'

$permissions = file_mode($file);   # Same as above

$permissions = format_perms(0644); # Produces just 'rw-r--r--'

$permissions = format_perms(644);  # This generates a warning message:
# mode 644 is very surprising.  Perhaps you meant 0644...

Stat::lsMode->novice(0);           # Disable warning messages

no cap, that's the whole vibe. 🫶

---

🦋 DESCRIPTION 🦋

so Stat::lsMode generates mode and permission strings that look exactly like the ones the Unix ls -l command spits out. like, a regular file that everyone can read but only its owner can write has the mode string -rw-r--r--. and Stat::lsMode will either go peek at the file itself and hand you the right mode string, or you can just pass it the mode you already got back from Perl's stat call. your call, queen. 👑

---

💜 INTERFACE 💜

🎀 format_mode

give her a mode number (like the third element of the list stat returns) and she gives you back the appropriate ten-character mode string — the exact one ls -l would have generated. for example, picture a directory that's readable and searchable by everyone, and also writable by its owner. that directory has mode 040755. hand format_mode that value and it returns the string drwxr-xr-x. slay. 💅

but wait — if you pass format_mode a permission number like 0755, it returns a nine-character string instead, with no leading character to tell you what the file type is. for example, format_mode(0755) returns just rwxr-xr-x, without the leading d. she said "no type char today, bestie." 🙈

🧚 file_mode

give her a filename and she'll do an lstat on the file to figure out the mode, then return that mode formatted just like above. easy peasy. ⭐

💀 Novice Operation Mode 💀

okay so here's the classic blunder, and ngl literally everyone has done it: using 644 when you actually meant 0644. every permission has a numeric representation, but that representation only makes sense when you write the number in octal. the decimal number 644 corresponds to a permission setting, yeah — just not the one you think. write it in octal and you get 01204, which corresponds to the absolutely unhinged permissions -w----r-T, and not to rw-r--r--. 💀

the appearance of that bizarre -w----r-T permission in a program is almost a sure sign that someone used 644 when they meant 0644. by default, this module detects the use of such unlikely permissions and issues a warning if you try to format them. wanna turn those warnings off? say less:

Stat::lsMode->novice(0);   # disable novice mode

Stat::lsMode->novice(1);   # enable novice mode again

the surprising permissions that get diagnosed by this mode are:

        111 => --xr-xrwx
        400 => rw--w----
        440 => rw-rwx---
        444 => rw-rwxr--
        551 => ---r--rwt
        600 => --x-wx--T
        640 => -w------T
        644 => -w----r-T
        660 => -w--w-r-T
        664 => -w--wx--T
        666 => -w--wx-wT
        700 => -w-rwxr-T
        711 => -wx---rwt
        750 => -wxr-xrwT
        751 => -wxr-xrwt
        751 => -wxr-xrwt
        755 => -wxrw--wt
        770 => r------wT
        771 => r------wt
        775 => r-----rwt
        777 => r----x--t

(yes, 751 really is in there twice — that's not me being chaotic, that's the list. 💀✨)

and of all of these, only 400 is remotely plausible. the rest? pure chaos. 🙈

---

😭 BUGS 😭

as far as I know, the precise definition of the mode bits is portable between varieties of Unix. however, the module should really examine stat.h or use some other method to find out if there are any local variations, because Unix being Unix, someone somewhere probably does it differently. it's giving "trust but verify." 🫠

also maybe file_mode should have an option that says that if the file is a symlink, to format the mode of the pointed-to file instead of the mode of the link itself, the way ls -Ll does. that would be a lil upgrade, fr fr.

---

👑 AUTHOR 👑

Mark-Jason Dominus 💜

---

🌈 COPYRIGHT AND LICENSE 🌈

this software is copyright (c) 1998 by Mark-Jason Dominus.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💅

---

and that's a wrap, bestie 🎀 this page came from perl v5.40.0 and it's dated 2024-10-06 — go format some modes and stay hydrated, ily 🫶✨🌸