---
name: "File::stat"
section: "3perl"
platform: "linux"
package: "perl"
version: "5.44.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/File::stat/3perl"
---

# File::stat(3perl)

by-name interface to Perl's built-in stat() functions

## NAME

File::stat - by-name interface to Perl's built-in stat() functions

## SYNOPSIS

```
    use File::stat;
    my $st = stat($file) or die "No $file: $!";
    if ( ($st->mode & 0111) && ($st->nlink > 1) ) {
        print "$file is executable with lotsa links\n";
    }
    if ( -x $st ) {
        print "$file is executable\n";
    }
    use Fcntl "S_IRUSR";
    if ( $st->cando(S_IRUSR, 1) ) {
        print "My effective uid can read $file\n";
    }
    use File::stat qw(:FIELDS);
    stat($file) or die "No $file: $!";
    if ( ($st_mode & 0111) && ($st_nlink > 1) ) {
        print "$file is executable with lotsa links\n";
    }
```

## DESCRIPTION

This module's default exports override the core **stat()** and **lstat()** functions, replacing them with versions that return "File::stat" objects.  This object has methods that return the similarly named structure field name from the [**stat**(2)](/stat/2.md) function; namely, dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, and blocks.

As of version 1.02 (provided with perl 5.12) the object provides `"-X"` overloading, so you can call filetest operators (`"-f"`, `"-x"`, and so on) on it. It also provides a `"->cando"` method, called like

```
    $st->cando( ACCESS, EFFECTIVE )
```

where *ACCESS* is one of `"S_IRUSR"`, `"S_IWUSR"` or `"S_IXUSR"` from the Fcntl module, and *EFFECTIVE* indicates whether to use effective (true) or real (false) ids. The method interprets the `"mode"`, `"uid"` and `"gid"` fields, and returns whether or not the current process would be allowed the specified access.

If you don't want to use the objects, you may import the `"->cando"` method into your namespace as a regular function called `"stat_cando"`. This takes an arrayref containing the return values of `"stat"` or `"lstat"` as its first argument, and interprets it for you.

You may also import all the structure fields directly into your namespace 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.

To access this functionality without the core overrides, pass the `"use"` an empty import list, and then access functions with their full qualified names:

```
    use File::stat ();
    my $st = File::stat::stat($file);
```

On the other hand, the built-ins are still available via the `"CORE::"` pseudo-package even if you let File::stat override them:

```
    use File::stat;
    my ($dev, $ino, $mode) = CORE::stat($file);
```

As of version 1.15 (provided with perl 5.44) `"stat"` and `"lstat"` can be called without arguments, in which case `$_` is used (just like the built-in `"stat"`/`"lstat"` functions):

```
    my $st_1 = stat;   # stat($_)
    my $st_2 = lstat;  # lstat($_)
```

## BUGS

The built-in `"stat"` and `"lstat"` functions recognize the special filehandle `"_"` (underscore) to indicate that no actual `"stat"` be done; instead the results of the last `"stat"` or `"lstat"` or filetest operation should be returned.  This syntax does not work with File::stat, but the same result can be achieved by passing `"stat"` a reference to the `*_` typeglob:

```
    use File::stat;
    my $stat_obj = stat \*_;  # reuse results of last stat operation
```

Alternatively, another workaround is to explicitly populate the object using the unexported and undocumented **populate()** function with **CORE::stat()**:

```
    my $stat_obj = File::stat::populate(CORE::stat(_));
```

## ERRORS

- \-%s is not implemented on a File::stat object

  The filetest operators `"-t"`, `"-T"` and `"-B"` are not implemented, as they require more information than just a stat buffer.

## WARNINGS

These can all be disabled with

```
    no warnings "File::stat";
```

- File::stat ignores use filetest 'access'

  You have tried to use one of the `"-rwxRWX"` filetests with `"use` `filetest 'access'"` in effect. `"File::stat"` will ignore the pragma, and just use the information in the `"mode"` member as usual.

- File::stat ignores VMS ACLs

  VMS systems have a permissions structure that cannot be completely represented in a stat buffer, and unlike on other systems the builtin filetest operators respect this. The `"File::stat"` overloads, however, do not, since the information required is not available.

## NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

## AUTHOR

Tom Christiansen