view release on metacpan or  search on metacpan

stat.pm  view on Meta::CPAN

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.

=head2 BSD::stat vs. CORE::stat

When called as array context, C<lstat()> and C<stat()> return an array
like CORE::stat. Here are the meaning of the fields:

  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.

C<atimespec>, C<mtimespec>, C<ctimespec> are available only as methods
that return times in floating point.

  my $st = stat($path);
  printf "%f\n" $st->atimespec; # $st->atime + $st->atimensec / 1e9

=head2 BSD::stat vs File::stat

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 C<st_> in
front their method names. Thus, C<$stat_obj-E<gt>dev()> corresponds to
$st_dev if you import the fields.

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

=head2 chflags

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;

=head2 utimes and lutimes

C<utimes()> and C<lutimes()) are introduced in version 1.30.

C<utimes()> is identical to C<utime()> except fractional time is accepted.

C<lutimes()> is identical to C<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.

=head1 PERFORMANCE

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?

=head1 EXPORT

stat(), lstat(), chflags() and chflags-related constants are exported
as default. $st_* variables are also exported when used with :FIELDS

=head1 BUGS

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.

=head1 SEE ALSO

L<chflags/2>
L<stat/2>
L<File::stat>
L<perlfunc/-x>
L<perlfunc/stat>

=head1 SUPPORT

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