view release on metacpan or  search on metacpan

stat.pm  view on Meta::CPAN

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.

    perldoc BSD::stat

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=BSD-stat>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/BSD-stat>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/BSD-stat>

=item * Search CPAN

L<http://search.cpan.org/dist/BSD-stat/>