No::Worries::Stat(3)

💅 No::Worries::Stat — stat() without the stress 💅

okay so welcome to the No::Worries::Stat(3) page, bestie — it’s giving User Contributed Perl Documentation, but make it cute. This is your little file-status helper module, and it wants you to understand every single thing. 🫶

---

✨ NAME ✨

No::Worries::Stat — stat() handling without worries. That’s the whole vibe, no cap. 💖

---

🦋 SYNOPSIS 🦋

use No::Worries::Stat qw(*);

@stat = stat($path) or die;
printf("type is %s\n", stat_type($stat[ST_MODE]));
printf("size is %d\n", $stat[ST_SIZE]);
printf("user can read\n") if $stat[ST_MODE] & S_IRUSR;

# make sure "/bin/ls" is owned by root and has the right permissions
stat_ensure("/bin/ls", user => "root", mode => 0755);
# make sure "/var/log" is not group or world writable
stat_ensure("/var/log", mode => "-022");
# idem but using the S_* constants
stat_ensure("/var/log", mode => "-" . (S_IWGRP|S_IWOTH));

---

💖 DESCRIPTION 💖

This module eases file status handling by providing convenient constants and functions to get, set and manipulate file status information. All the functions die() on error — so no quiet little failures, okay? 😭

---

🎀 CONSTANTS 🎀

This module provides the following constants to ease access to stat() fields (none of them being exported by default):

• ST_DEV — ID of device containing file
• ST_INO — inode number
• ST_MODE — protection
• ST_NLINK — number of hard links
• ST_UID — user ID of owner
• ST_GID — group ID of owner
• ST_RDEV — device ID (if special file)
• ST_SIZE — total size, in bytes
• ST_ATIME — time of last access
• ST_MTIME — time of last modification
• ST_CTIME — time of last status change
• ST_BLKSIZE — blocksize for filesystem I/O
• ST_BLOCKS — number of 512B blocks allocated

In addition, it also optionally exports all the :mode constants from Fcntl.

This way, all the stat() related constants can be imported in a uniform way. Slay. 💅

---

💅 FUNCTIONS 💅

This module provides the following functions (none of them being exported by default):

stat_type(MODE)

Given the file mode (ST_MODE field), return the file type as a string. The possible return values are: block device, character device, directory, door, event port, network file, pipe, plain file, socket, symlink, unknown and whiteout. 🦋

stat_ensure(PATH[, OPTIONS])

Make sure the given path has the expected file status (w.r.t. stat()) and call chown(), chmod() or utime() if needed, returning the number of changes performed. Supported options:

• user — expected user name or uid
• group — expected group name or gid
• mode — expected mode specification (see below)
• mtime — expected modification time
• follow — follow symbolic links (default is to skip them)
• callback — code to be executed before changing something (see below)

The mode option of stat_ensure() can be given:

• NUMBER — an absolute value like 0755, meaning that mode must be equal to it
• +NUMBER — a list of bits that must be set, e.g. +0111 for "executable for all"
• -NUMBER — a list of bits that must be clear, e.g. -022 for not writable by group or other

Note, bestie: the number after + or - will be interpreted as being octal only if it starts with 0. You should therefore use +0111 or +.oct(111) to enable the executable bits but not +111 which is the same as +0157. Lowkey important, don’t skip it. 🔥

The callback option of stat_ensure() will receive the given path and a string describing what is about to be changed. It must return true to tell stat_ensure() to indeed perform the changes.

Here’s how a noaction option could be implemented:

sub noaction ($$) {
    my($path, $change) = @_;

    printf("did not change %s of %s\n", $change, $path);
    return(0);
}
foreach my $path (@paths) {
    stat_ensure($path, user => "root", mode => 0755, callback => \&noaction);
}

---

🌈 SEE ALSO 🌈

Fcntl, No::Worries. Go peek at them, they’re part of the friend group. 💜

---

👑 AUTHOR 👑

Lionel Cons <http://cern.ch/lionel.cons>

Copyright (C) CERN 2012-2019

---

💖 That’s the whole page, bestie — brought to you by No::Worries::Stat(3), perl v5.32.1, and 2021-10-18. Periodt. 🎀