File::stat dies on path objects with overloaded stringification

[mauke]

Module: File::stat

Description
File::stat is supposed to implement the interface of CORE::stat, which lets you pass a filehandle or the name of a file. If you pass an object with overloaded stringification (such as as instance of Path::Tiny), it should use the stringified form of the object without triggering an error, even if the referenced name does not exist. However, this only works as expected if stat succeeds; if stat fails, it unexpectedly throws an exception ("Not a GLOB reference") instead of returning undef.

Steps to Reproduce

$ perl -e 'use File::stat; use Path::Tiny; stat path("/ no such file")'
Not a GLOB reference at /home/mauke/perl5/perlbrew/perls/perl-5.42.0/lib/5.42.0/File/stat.pm line 208.

Or standalone:

# bug.pl
use strict;
use warnings;

use File::stat;

{
    package Dummy;
    use overload
        '""'     => sub { $_[0]->to_string },
        fallback => 1;

    sub new {
        my $class = shift;
        bless { path => $_[0] }, $class
    }

    sub to_string {
        my $self = shift;
        $self->{path}
    }
}

my $p = Dummy->new("/ no such file");

stat "$p";
print "stat('$p') didn't die (explicitly stringified)\n";

stat $p;
print "stat('$p') didn't die (as path object)\n";

$ ./perl -Ilib bug.pl
stat('/ no such file') didn't die (explicitly stringified)
Not a GLOB reference at lib/File/stat.pm line 208.

Expected behavior
I expect a failing stat to silently return undef without dying. Just like the success case:

$ perl -e 'use File::stat; use Path::Tiny; stat path("/")
$

Perl configuration

Summary of my perl5 (revision 5 version 43 subversion 2) configuration:
  Derived from: 976a00d6edf2334539e653f32b592dae55092868
  Platform:
    osname=linux
    osvers=6.11.0-120029-tuxedo
    archname=x86_64-linux
    uname='linux luum 6.11.0-120029-tuxedo #29~24.04.1tux2 smp preempt_dynamic wed jul 2 13:51:09 utc 2025 x86_64 x86_64 x86_64 gnulinux '
    config_args='-Dcc=c-gcc -Dusedevel -des -DDEBUGGING'
    hint=recommended
    useposix=true
    d_sigaction=define
    useithreads=undef
    usemultiplicity=undef
    use64bitint=define
    use64bitall=define
    uselongdouble=undef
    usemymalloc=n
    default_inc_excludes_dot=define
  Compiler:
    cc='c-gcc'
    ccflags ='-fwrapv -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
    optimize='-O2 -g'
    cppflags='-fwrapv -DDEBUGGING -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion=''
    gccversion='13.3.0'
    gccosandvers=''
    intsize=4
    longsize=8
    ptrsize=8
    doublesize=8
    byteorder=12345678
    doublekind=3
    d_longlong=define
    longlongsize=8
    d_longdbl=define
    longdblsize=16
    longdblkind=3
    ivtype='long'
    ivsize=8
    nvtype='double'
    nvsize=8
    Off_t='off_t'
    lseeksize=8
    alignbytes=8
    prototype=define
  Linker and Libraries:
    ld='c-gcc'
    ldflags =' -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/x86_64-linux-gnu /usr/lib /usr/lib64
    libs=-lpthread -ldb -ldl -lm -lcrypt -lutil -lc
    perllibs=-lpthread -ldl -lm -lcrypt -lutil -lc
    libc=/lib/x86_64-linux-gnu/libc.so.6
    so=so
    useshrplib=false
    libperl=libperl.a
    gnulibc_version='2.39'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs
    dlext=so
    d_dlsymun=undef
    ccdlflags='-Wl,-E'
    cccdlflags='-fPIC'
    lddlflags='-shared -O2 -g -L/usr/local/lib -fstack-protector-strong'


Characteristics of this binary (from libperl): 
  Compile-time options:
    DEBUGGING
    HAS_LONG_DOUBLE
    HAS_STRTOLD
    HAS_TIMES
    PERLIO_LAYERS
    PERL_COPY_ON_WRITE
    PERL_DONT_CREATE_GVSV
    PERL_HASH_FUNC_SIPHASH13
    PERL_HASH_USE_SBOX32
    PERL_MALLOC_WRAP
    PERL_OP_PARENT
    PERL_PRESERVE_IVUV
    PERL_USE_DEVEL
    PERL_USE_SAFE_PUTENV
    USE_64_BIT_ALL
    USE_64_BIT_INT
    USE_LARGE_FILES
    USE_LOCALE
    USE_LOCALE_COLLATE
    USE_LOCALE_CTYPE
    USE_LOCALE_NUMERIC
    USE_LOCALE_TIME
    USE_PERLIO
    USE_PERL_ATOF
  Locally applied patches:
    uncommitted-changes
  Built under linux
  Compiled at Jul 29 2025 23:33:21
  %ENV:
    PERLBREW_BASHRC_VERSION="0.74"
    PERLBREW_HOME="/home/mauke/.perlbrew"
    PERLBREW_MANPATH="/home/mauke/perl5/perlbrew/perls/perl-5.42.0/man"
    PERLBREW_PATH="/home/mauke/perl5/perlbrew/bin:/home/mauke/perl5/perlbrew/perls/perl-5.42.0/bin"
    PERLBREW_PERL="perl-5.42.0"
    PERLBREW_ROOT="/home/mauke/perl5/perlbrew"
    PERLBREW_VERSION="0.98"
    PERLDOC="-oman"
    PERL_UNICODE="SAL"
  @INC:
    lib
    /usr/local/lib/perl5/site_perl/5.43.2/x86_64-linux
    /usr/local/lib/perl5/site_perl/5.43.2
    /usr/local/lib/perl5/5.43.2/x86_64-linux
    /usr/local/lib/perl5/5.43.2

[jkeenan]

Module: File::stat

Description File::stat is supposed to implement the interface of CORE::stat, which lets you pass a filehandle or the name of a file. If you pass an object with overloaded stringification (such as as instance of Path::Tiny), it should use the stringified form of the object without triggering an error, even if the referenced name does not exist. However, this only works as expected if stat succeeds; if stat fails, it unexpectedly throws an exception ("Not a GLOB reference") instead of returning undef.

@mauke has filed two pull requests (GH #23507 and GH #23508) referencing this issue, but as of yet no one has commented on the issue itself. I don't have any special competence with regard to File::stat or to stat, but I think we could use some discussion of these points:

1. " If you pass an object with overloaded stringification ..., it should use the stringified form of the object without triggering an error ..." Do we agree?
2. "this only works as expected if stat succeeds; if stat fails, it unexpectedly throws an exception ("Not a GLOB reference") instead of returning undef." Do we agree with the argument for returning undef?

[Grinnz]

I agree with both of those points, as the error is clearly not intentional.

[mauke]

My rationale:

Re stringifying objects: That's what the built-in stat/lstat functions do. Overrides like the ones from File::stat should mimic that behavior as much as reasonably possible. Also, it's what File::stat already does. If the internal stat call on the stringified object succeeds, it silently succeeds, too. Only if the internal stat call on the stringified object fails, it throws an internal error. At minimum, it's inconsistent.

Re return value: Surprisingly, the return value of File::stat::stat in case of failure is not documented explicitly, but the synopsis shows that it must be a false value (it uses stat($file) or die ...). Looking at the code I see it has always (for the last 29 years) returned an empty list in list context and undef in scalar context to signal failure. The only documented and intentionally thrown error in File::stat is "-t (or -T or -B) is not implemented on a File::stat object", which is not relevant here. So throwing a cryptic "Not a GLOB reference" error does not conform to the API implied by the module's synopsis nor does it match File::stat's behavior in other cases where the internal stat call fails (where it has always returned ()/undef).