The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
BSD-stat-1.35
River stage zero No dependents
++
/ BSD::stat

NAME

BSD::stat - stat() with BSD 4.4 extentions

SYNOPSIS

  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;

DESCRIPTION

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.

BSD::stat vs. CORE::stat

When called as array context, lstat() and 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.

atimespec, mtimespec, 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

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 st_ in front their method names. Thus, $stat_obj->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

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;

utimes and lutimes

utimes() and lutimes()) are introduced in version 1.30.

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

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.

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?

EXPORT

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

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.

SEE ALSO

"2" in chflags "2" in stat File::stat "-x" in perlfunc "stat" in perlfunc

SUPPORT

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

    perldoc BSD::stat

You can also look for information at:

AUTHOR

Dan Kogai <dankogai@dan.co.jp>

COPYRIGHT & LICENSE

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:

Around line 357:

Unterminated C<...> sequence