BSD::stat - stat() with BSD 4.4 extentions
use BSD::stat; # just like CORE::stat ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, $atime,$mtime,$ctime,$blksize,$blocks, $atimensec,$mtimensec,$ctimensec,$flags,$gen) = stat($filename); # BSD::stat now accepts filehandles, too open F, "foo"; my @stat = stat(*F); # omit an argument and it will use $_; my $_ = "foo"; my stat = stat; # stat($file) then -x _ works like CORE::stat(); stat("foo") and -x _ and print "foo is executable" # but -x $file then stat(_) will not!!! # just like File::stat $st = stat($file) or die "No $file: $!"; if ( ($st->mode & 0111) && $st->nlink > 1) ) { print "$file is executable with lotsa links\n"; } use BSD::stat qw(:FIELDS); stat($file) or die "No $file: $!"; if ( ($st_mode & 0111) && $st_nlink > 1) ) { print "$file is executable with lotsa links\n"; } # chflags chflags(UF_IMMUTABLE, @files) # utimes and lutimes my $when = 1234567890.987654; utimes $when, $when, @files; lutimes $when, $when, @links;
This module's default exports override the core stat() and lstat() functions, replacing them with versions that contain BSD 4.4 extentions such as file flags. This module also adds chflags function.
When called as array context, lstat() and stat() return an array like CORE::stat. Here are the meaning of the fields:
lstat()
stat()
0 dev device number of filesystem 1 ino inode number 2 mode file mode (type and permissions) 3 nlink number of (hard) links to the file 4 uid numeric user ID of file's owner 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes 8 atime last access time in seconds since the epoch 9 mtime last modify time in seconds since the epoch 10 ctime inode change time (NOT creation time!) in seconds si 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated 13 atimensec nsec of last access 14 mtimensec nsec of last data modification 15 ctimensec nsec of last file status change 16 flags user defined flags for file 17 gen file generation number
Like CORE::stat, BSD::stat supports _ filehandle. It does set "stat cache" so the following -x _ operators can benefit. Be careful, however, that BSD::stat::stat(_) will not work (or cannot be made to work) because BSD::stat::stat() holds more info than that is stored in Perl's internal stat cache.
atimespec, mtimespec, ctimespec are available only as methods that return times in floating point.
atimespec
mtimespec
ctimespec
my $st = stat($path); printf "%f\n" $st->atimespec; # $st->atime + $st->atimensec / 1e9
When called as scalar context, it returns an object whose methods are named as above, just like File::stat.
Like File::stat, You may also import all the structure fields directly nto yournamespace as regular variables using the :FIELDS import tag. (Note that this still overrides your stat() and lstat() functions.) Access these fields as variables named with a preceding st_ in front their method names. Thus, $stat_obj->dev() corresponds to $st_dev if you import the fields.
st_
$stat_obj->dev()
Note: besides polluting the name space, :FIELDS comes with performance penalty for setting extra variables. Unlike File::stat which always sets $File::stat::st_* (even when not exported), BSD::stat implements its own import mechanism to prevent performance loss when $st_* is not needed
BSD::stat also adds chflags(). Like CORE::chmod it takes first argument as flags and any following arguments as filenames. for convenience, the followin constants are also set;
UF_SETTABLE 0x0000ffff /* mask of owner changeable flags */ UF_NODUMP 0x00000001 /* do not dump file */ UF_IMMUTABLE 0x00000002 /* file may not be changed */ UF_APPEND 0x00000004 /* writes to file may only append */ UF_OPAQUE 0x00000008 /* directory is opaque wrt. union * UF_NOUNLINK 0x00000010 /* file may not be removed or renamed */ SF_SETTABLE 0xffff0000 /* mask of superuser changeable flags */ SF_ARCHIVED 0x00010000 /* file is archived */ SF_IMMUTABLE 0x00020000 /* file may not be changed */ SF_APPEND 0x00040000 /* writes to file may only append */ SF_NOUNLINK 0x00100000 /* file may not be removed or renamed */
so that you can go like
chflags(SF_ARCHIVED|SF_IMMUTABLE, @files);
just like CORE::chmod(), chflags() returns the number of files successfully changed. when an error occurs, it sets !$ so you can check what went wrong when you applied only one file.
to unset all flags, simply
chflags 0, @files;
utimes() and lutimes()) are introduced in version 1.30.
utimes()
lutimes()) are introduced in version 1.30.
utimes() is identical to utime() except fractional time is accepted.
utime()
lutimes() is identical to utimes() except when the path is symbolic link, in which case it changes the time stamp of the symlink link instead of the file it links to.
lutimes()
You can use t/benchmark.pl to test the perfomance. Here is the result on my FreeBSD box.
Benchmark: timing 100000 iterations of BSD::stat, Core::stat, File::stat... BSD::stat: 3 wallclock secs ( 2.16 usr + 0.95 sys = 3.11 CPU) @ 32160.80/s (n=100000) Core::stat: 1 wallclock secs ( 1.18 usr + 0.76 sys = 1.94 CPU) @ 51612.90/s (n=100000) File::stat: 7 wallclock secs ( 6.40 usr + 0.93 sys = 7.33 CPU) @ 13646.06/s (n=100000)
Not too bad, huh?
stat(), lstat(), chflags() and chflags-related constants are exported as default. $st_* variables are also exported when used with :FIELDS
This is the best approximation of CORE::stat() and File::stat::stat() that module can go.
In exchange of '_' support, BSD::stat now peeks and pokes too much of perlguts in terms tat BSD::stat uses such variables as PL_statcache that does not appear in "perldoc perlapi" and such.
Very BSD specific. It will not work on any other platform.
"2" in chflags "2" in stat File::stat "-x" in perlfunc "stat" in perlfunc
You can find documentation for this module with the perldoc command.
perldoc BSD::stat
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=BSD-stat
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/BSD-stat
CPAN Ratings
http://cpanratings.perl.org/d/BSD-stat
Search CPAN
http://search.cpan.org/dist/BSD-stat/
Dan Kogai <dankogai@dan.co.jp>
Copyright 2001-2012 Dan Kogai, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Unterminated C<...> sequence
To install BSD::stat, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BSD::stat
CPAN shell
perl -MCPAN -e shell install BSD::stat
For more information on module installation, please visit the detailed CPAN module installation guide.