NAME

No::Worries::Stat - stat() handling without worries

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.

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.

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; 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: 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".

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 is for insatnce 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.

AUTHOR

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

Copyright (C) CERN 2012-2017