[PATCH] Document -l on symlinkless file systems

[p5pRT]

Migrated from rt.perl.org#121523 (status was 'resolved')

Searchable as RT121523$

[p5pRT]

From @Smylers

This is a bug report for perl from Smylers@​stripey.com,
generated with the help of perlbug 1.40 running under perl 5.19.11.

---

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

---

---

Flags​:
  category=docs
  severity=low
  Type=Patch
  PatchStatus=HasPatch

---

Site configuration information for perl 5.19.11​:

Configured by smylers at Fri Mar 28 15​:10​:22 GMT 2014.

Summary of my perl5 (revision 5 version 19 subversion 11) configuration​:
  Derived from​: 721b267
  Platform​:
  osname=linux, osvers=3.11.0-19-generic, archname=x86_64-linux
  uname='linux fozzie 3.11.0-19-generic #33-ubuntu smp tue mar 11 18​:48​:34 utc 2014 x86_64 x86_64 x86_64 gnulinux '
  config_args='-des -Dusedevel'
  hint=previous, useposix=true, d_sigaction=define
  useithreads=undef, usemultiplicity=undef
  use64bitint=define, use64bitall=define, uselongdouble=undef
  usemymalloc=n, bincompat5005=undef
  Compiler​:
  cc='cc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
  optimize='-O2',
  cppflags='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
  ccversion='', gccversion='4.8.1', gccosandvers=''
  intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
  d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
  ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
  alignbytes=8, prototype=define
  Linker and Libraries​:
  ld='cc', ldflags =' -fstack-protector -L/usr/local/lib'
  libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.8/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib /usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.8/include-fixed /usr/include/x86_64-linux-gnu /usr/lib
  libs=-lnsl -ldl -lm -lcrypt -lutil -lc
  perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
  libc=libc-2.17.so, so=so, useshrplib=false, libperl=libperl.a
  gnulibc_version='2.17'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
  cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector'

Locally applied patches​:
  uncommitted-changes

---

@​INC for perl 5.19.11​:
  lib
  /usr/local/lib/perl5/site_perl/5.19.11/x86_64-linux
  /usr/local/lib/perl5/site_perl/5.19.11
  /usr/local/lib/perl5/5.19.11/x86_64-linux
  /usr/local/lib/perl5/5.19.11
  .

---

Environment for perl 5.19.11​:
  HOME=/home/smylers
  LANG=en_GB.utf8
  LANGUAGE=en_GB​:en
  LC_COLLATE=C
  LD_LIBRARY_PATH (unset)
  LOGDIR (unset)
  PATH=/home/smylers/bin​:/usr/local/sbin​:/usr/local/bin​:/sbin​:/bin​:/usr/sbin​:/usr/bin​:/usr/X11R6/bin​:/usr/games
  PERL_BADLANG (unset)
  PERL_CPANM_OPT=--sudo --prompt
  SHELL=/bin/bash

[p5pRT]

From @Smylers

0001-Document-l-on-symlinkless-file-systems.patch

From e49358ba8408e36cae966dddacd24eac9f173bb6 Mon Sep 17 00:00:00 2001
From: Smylers <Smylers@stripey.com>
Date: Fri, 28 Mar 2014 16:33:05 +0000
Subject: [PATCH] Document -l on symlinkless file systems

We can rely on -l always being false on platforms that don't support
symlinks:
http://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html
---
 pod/perlfunc.pod | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index b8af8ff..754ed17 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -378,7 +378,8 @@ other named unary operator.  The operator may be any of:
 
     -f  File is a plain file.
     -d  File is a directory.
-    -l  File is a symbolic link.
+    -l  File is a symbolic link (false if symlinks aren't
+        supported by the file system).
     -p  File is a named pipe (FIFO), or Filehandle is a pipe.
     -S  File is a socket.
     -b  File is a block special file.
-- 
1.8.3.2

[p5pRT]

From @iabyn

On Fri, Mar 28, 2014 at 09​:37​:49AM -0700, Smylers wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

I don't understand why a new ticket was needed for this; my follow-up
reply has been attached to ticket #72028, and I'll close this one
shortly.

--
I thought I was wrong once, but I was mistaken.

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @Smylers

Dave Mitchell writes​:

On Fri, Mar 28, 2014 at 09​:37​:49AM -0700, Smylers wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

I don't understand why a new ticket was needed for this; my follow-up
reply has been attached to ticket #72028

Apologies if I've misunderstood, but it looked to me like #72028 is
about fixing a problem with installing some utility programs. This
ticket is about improving the user documentation of the -l function.

The gap in the current -l documentation appeared to be identified by
your asking about it in the process of working on #72028, but I think
the two tickets are independent matters​: this doc patch could be applied
regardless of the fix for #72028 (or vice versa).

Hope that makes sense.

Cheers

Smylers
--
http​://twitter.com/Smylers2

[p5pRT]

From @khwilliamson

On 03/29/2014 04​:14 PM, Smylers wrote​:

Dave Mitchell writes​:

On Fri, Mar 28, 2014 at 09​:37​:49AM -0700, Smylers wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

I don't understand why a new ticket was needed for this; my follow-up
reply has been attached to ticket #72028

Apologies if I've misunderstood, but it looked to me like #72028 is
about fixing a problem with installing some utility programs. This
ticket is about improving the user documentation of the -l function.

The gap in the current -l documentation appeared to be identified by
your asking about it in the process of working on #72028, but I think
the two tickets are independent matters​: this doc patch could be applied
regardless of the fix for #72028 (or vice versa).

Hope that makes sense.

Cheers

Smylers

The doc patch seems to me to be a worthwhile addition. Are there
objections to applying it?

[p5pRT]

From @ikegami

It seems self-evident to me that a file can't be symlink on a system
without symlinks. I see no value to the patch, but I see no harm either.

I was about to comment "defined false" would be better than false, but it's
implied earlier on in the documentation that false is different than undef.

(It claims that an empty string is returned for false, which is inaccurate.
It claims that a returned undef signals that the file doesn't exist, which
is inaccurate.)

On Sat, Mar 29, 2014 at 11​:32 PM, Karl Williamson
<public@​khwilliamson.com>wrote​:

On 03/29/2014 04​:14 PM, Smylers wrote​:

Dave Mitchell writes​:

On Fri, Mar 28, 2014 at 09​:37​:49AM -0700, Smylers wrote​:

Documenting Zefram's reply to Dave M's question about -l​:

http​://www.nntp.perl.org/group/perl.perl5.porters/2014/
03/msg214012.html

I don't understand why a new ticket was needed for this; my follow-up
reply has been attached to ticket #72028

Apologies if I've misunderstood, but it looked to me like #72028 is
about fixing a problem with installing some utility programs. This
ticket is about improving the user documentation of the -l function.

The gap in the current -l documentation appeared to be identified by
your asking about it in the process of working on #72028, but I think
the two tickets are independent matters​: this doc patch could be applied
regardless of the fix for #72028 (or vice versa).

Hope that makes sense.

Cheers

Smylers

The doc patch seems to me to be a worthwhile addition. Are there
objections to applying it?

[p5pRT]

From @Smylers

Eric Brine via RT writes​:

It seems self-evident to me that a file can't be symlink on a system
without symlinks.

The fact that Dave M posed the question suggests there are at least some
to whom it isn't evident.

(It claims that an empty string is returned for false, which is
inaccurate. It claims that a returned undef signals that the file
doesn't exist, which is inaccurate.)

What would be accurate to say instead? We may as well fix that part of
the docs now you've spotted it.

Smylers
--
http​://twitter.com/Smylers2

[p5pRT]

From @iabyn

On Sun, Mar 30, 2014 at 07​:19​:53PM +0100, Smylers wrote​:

Eric Brine via RT writes​:

It seems self-evident to me that a file can't be symlink on a system
without symlinks.

The fact that Dave M posed the question suggests there are at least some
to whom it isn't evident.

For example it occurred to me that on platforms that don't support
symlinks, -l might well croak rather than return false. Even if it
currently returned false, unless that behaviour was documented, it would
be behaviour I shouldn't be relying upon.

--
Hofstadter's Law​: It always takes longer than you expect, even when you
take into account Hofstadter's Law.

[p5pRT]

From @ikegami

On Wed, Apr 2, 2014 at 7​:19 AM, Dave Mitchell <davem@​iabyn.com> wrote​:

For example it occurred to me that on platforms that don't support
symlinks, -l might well croak rather than return false. Even if it
currently returned false, unless that behaviour was documented, it would
be behaviour I shouldn't be relying upon.

The behaviour is documented​: It's documented to return false if it's not a
symlink. Croaking would be a deviation, and it should be documented in
perlport.

Out of curiosity, what platform supported by Perl doesn't support symlinks?
VMS?

[p5pRT]

From @craigberry

On Wed, Apr 2, 2014 at 9​:53 AM, Eric Brine <ikegami@​adaelis.com> wrote​:

Out of curiosity, what platform supported by Perl doesn't support symlinks?
VMS?

VMS 8.3 (released in 2006) and later support symlinks. You have to
have the right volume settings as well as OS version to get symlink
support. There are some limitations but it works reasonably well.

I think it was Windows where there is a symlink implementation but
it's so different from Unixy expectations that it would be a
significant effort to write a layer on top of it so it could be useful
to Perl applications.

[p5pRT]

From @ikegami

On Wed, Apr 2, 2014 at 11​:15 AM, Craig A. Berry <craig.a.berry@​gmail.com>wrote​:

On Wed, Apr 2, 2014 at 9​:53 AM, Eric Brine <ikegami@​adaelis.com> wrote​:

Out of curiosity, what platform supported by Perl doesn't support
symlinks?
VMS?

VMS 8.3 (released in 2006) and later support symlinks. You have to
have the right volume settings as well as OS version to get symlink
support. There are some limitations but it works reasonably well.

I think it was Windows where there is a symlink implementation but
it's so different from Unixy expectations that it would be a
significant effort to write a layer on top of it so it could be useful
to Perl applications.

So there's a proposed change to clarify what happens on systems without
symlinks, when all systems have symlinks. It's even more useless than I
thought. If a clarification is needed, it's that it can return false even
for symlinks on Windows. But that belongs in perlport, right?

[p5pRT]

From @khwilliamson

On 04/02/2014 10​:24 AM, Eric Brine wrote​:

On Wed, Apr 2, 2014 at 11​:15 AM, Craig A. Berry <craig.a.berry@​gmail.com
<mailto​:craig.a.berry@​gmail.com>> wrote​:

On Wed\, Apr 2\, 2014 at 9&#8203;:53 AM\, Eric Brine \<ikegami@&#8203;adaelis\.com
\<mailto&#8203;:ikegami@&#8203;adaelis\.com>> wrote&#8203;:
 > Out of curiosity\, what platform supported by Perl doesn't support
symlinks?
 > VMS?

VMS 8\.3 \(released in 2006\) and later support symlinks\.  You have to
have the right volume settings as well as OS version to get symlink
support\.  There are some limitations but it works reasonably well\.

I think it was Windows where there is a symlink implementation but
it's so different from Unixy expectations that it would be a
significant effort to write a layer on top of it so it could be useful
to Perl applications\.

So there's a proposed change to clarify what happens on systems without
symlinks, when all systems have symlinks. It's even more useless than I
thought. If a clarification is needed, it's that it can return false
even for symlinks on Windows. But that belongs in perlport, right?

This claim doesn't sound right to me. It sounds to me like there are
platforms, including VMS, which don't have or are not configured to have
symlinks that Perl understands.

Further, there are subtle differences between
  return undef;
vs
  return;

Thus, a patch that correctly documents the behavior for this
circumstance seems to me to be an improvement that will help out people
trying to use Perl. I count myself as one of them.

[p5pRT]

From @craigberry

On Wed, Apr 2, 2014 at 12​:45 PM, Karl Williamson
<public@​khwilliamson.com> wrote​:

On 04/02/2014 10​:24 AM, Eric Brine wrote​:

On Wed, Apr 2, 2014 at 11​:15 AM, Craig A. Berry <craig.a.berry@​gmail.com
<mailto​:craig.a.berry@​gmail.com>> wrote​:

On Wed\, Apr 2\, 2014 at 9&#8203;:53 AM\, Eric Brine \<ikegami@&#8203;adaelis\.com
\<mailto&#8203;:ikegami@&#8203;adaelis\.com>> wrote&#8203;:
 > Out of curiosity\, what platform supported by Perl doesn't support
symlinks?
 > VMS?

VMS 8\.3 \(released in 2006\) and later support symlinks\.  You have to
have the right volume settings as well as OS version to get symlink
support\.  There are some limitations but it works reasonably well\.

I think it was Windows where there is a symlink implementation but
it's so different from Unixy expectations that it would be a
significant effort to write a layer on top of it so it could be useful
to Perl applications\.

So there's a proposed change to clarify what happens on systems without
symlinks, when all systems have symlinks. It's even more useless than I
thought. If a clarification is needed, it's that it can return false
even for symlinks on Windows. But that belongs in perlport, right?

This claim doesn't sound right to me.

Me either.

It sounds to me like there are
platforms, including VMS, which don't have or are not configured to have
symlinks that Perl understands.

VMS does have symlinks Perl understands, but underlying support is
version-specific, volume-specific, and configuration-specific. If
Perl ever added support for Windows symlinks (which I believe, but am
not certain is still not present), it would only be on NTFS and only
on certain versions of Windows.

Thus the patch is correct in saying, "false if symlinks aren't
supported by the file system," as it depends on capabilities of a
specific volume or file system in addition to platform capabilities.

Further, there are subtle differences between
return undef;
vs
return;

Thus, a patch that correctly documents the behavior for this circumstance
seems to me to be an improvement that will help out people trying to use
Perl.

I agree.

Now, about all of those blockers we haven't fixed yet....

[p5pRT]

From @ikegami

On Wed, Apr 2, 2014 at 1​:45 PM, Karl Williamson <public@​khwilliamson.com>wrote​:

Further, there are subtle differences between
return undef;
vs
return;

Thus, a patch that correctly documents the behavior for this circumstance
seems to me to be an improvement that will help out people trying to use
Perl. I count myself as one of them.

It shouldn't be returning either!

perl -wE"my @​rv = -l 'a'; say 0+@​rv; say defined($rv[0])?1​:0; say
$rv[0]?1​:0;"
1
1
0

Good. It doesn't.

[p5pRT]

From @tonycoz

On Fri Mar 28 09​:37​:49 2014, smylers@​stripey.com wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

There's a gap in the implementation too, while it would be almost pointless to implement symlink() on Win32[1], perhaps -l should work​:

  J​:\>perl -le "print 'link ', -l shift() ? 'yes' : 'no'" test
  link no
 
  J​:\>dir
  Volume in drive J is SSD
  Volume Serial Number is 742B-DD2C
 
  Directory of J​:\
 
  11/02/2014 03​:11 PM <DIR> dev
  14/04/2014 03​:02 PM 461 end
  25/03/2014 08​:06 AM <DIR> games
  05/02/2014 11​:06 AM <DIR> steam
  14/04/2014 03​:02 PM <SYMLINK> test [end]
  10/04/2014 11​:28 AM <DIR> VMs
  2 File(s) 461 bytes
  4 Dir(s) 176,709,697,536 bytes free

That said, implementing it would require a re-write of win32_stat(), since _stat()/_stati64() doesn't appear to return the appropriate flags.

Tony

[1] it requires admin access

[p5pRT]

From @tonycoz

On Fri Mar 28 09​:37​:49 2014, smylers@​stripey.com wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

I plan to apply this for 5.21.1.

Tony

[p5pRT]

From @tonycoz

On Fri Mar 28 09​:37​:49 2014, smylers@​stripey.com wrote​:

Documenting Zefram's reply to Dave M's question about -l​:
http​://www.nntp.perl.org/group/perl.perl5.porters/2014/03/msg214012.html

Thanks, applied as ae07d0f.

Tony

[p5pRT]

@tonycoz - Status changed from 'open' to 'resolved'