Skip Menu |
Report information
Id: 128607
Status: resolved
Priority: 0/
Queue: perl5

Owner: Nobody
Requestors: niczero [at] wow.com
Cc:
AdminCc:

Operating System: All
PatchStatus: (no value)
Severity: low
Type: docs
Perl Version: 5.25.2
Fixed In: (no value)



From: niczero [...] wow.com
To: perlbug [...] perl.org
Subject: POD: sysseek
Date: Tue, 12 Jul 2016 10:55:44 +0100
Download (untitled) / with headers
text/plain 3.1k
This is a bug report for perl from niczero@wow.com, generated with the help of perlbug 1.40 running under perl 5.24.0. ----------------------------------------------------------------- The POD for sysseek [perldoc -f sysseek] appears to me to have an error. In the second stanza it says Note the in bytes: even if the filehandle has been set to operate on characters (for example by using the ":encoding(utf8)" I/O layer), "tell" will return byte offsets, not character offsets (because implementing that would render "sysseek" unacceptably slow). Where it says "tell" I think it should say "sysseek". I suspect it shouldn't mention 'tell' at all, other than in the following stanza. ----------------------------------------------------------------- --- Flags: category=docs severity=low --- Site configuration information for perl 5.24.0: Configured by root at Mon May 16 22:00:30 BST 2016. Summary of my perl5 (revision 5 version 24 subversion 0) configuration: Platform: osname=linux, osvers=3.16.0-4-amd64, archname=x86_64-linux uname='linux dbdev 3.16.0-4-amd64 #1 smp debian 3.16.7-ckt20-1+deb8u4 (2016-02-29) x86_64 gnulinux ' config_args='-des' hint=recommended, useposix=true, d_sigaction=define useithreads=undef, usemultiplicity=undef use64bitint=define, use64bitall=define, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='cc', ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -D_FORTIFY_SOURCE=2', optimize='-O2', cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include' ccversion='', gccversion='4.9.2', 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='cc', ldflags =' -fstack-protector-strong -L/usr/local/lib' libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.9/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 libs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc libc=libc-2.19.so, so=so, useshrplib=false, libperl=libperl.a gnulibc_version='2.19' 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-strong' --- @INC for perl 5.24.0: /usr/local/lib/site_perl/x86_64-linux /usr/local/lib/site_perl /opt/perl/5.24.0/lib/x86_64-linux /opt/perl/5.24.0/lib . --- Environment for perl 5.24.0: HOME=/home/nsandfield LANG=en_GB.UTF-8 LANGUAGE=en_GB:en LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/usr/local/bin:/opt/perl/5.24.0/bin:/usr/bin:/bin PERL_BADLANG (unset) PERL_MB_OPT=--install_base /opt/perl/5.24.0 PERL_MM_OPT=INSTALL_BASE=/opt/perl/5.24.0 SHELL=/bin/bash
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 119b
Introduced in 9124316e, I agree that this is a typo (copy/pasted from other docs that were also added in that commit).
RT-Send-CC: perl5-porters [...] perl.org
On Tue Jul 12 02:56:05 2016, niczero@wow.com wrote: Show quoted text
> > This is a bug report for perl from niczero@wow.com, > generated with the help of perlbug 1.40 running under perl 5.24.0. > > > ----------------------------------------------------------------- > The POD for sysseek [perldoc -f sysseek] appears to me to have an > error. In the second stanza it says > > Note the in bytes: even if the filehandle has been set to operate > on characters (for example by using the ":encoding(utf8)" I/O > layer), "tell" will return byte offsets, not character offsets > (because implementing that would render "sysseek" unacceptably > slow). > > Where it says "tell" I think it should say "sysseek". I suspect > it shouldn't mention 'tell' at all, other than in the following > stanza. >
The text here is almost identical to a paragraph also found in pod/perlfunc.pod for 'tell' (perldoc -f tell). I'm pinging the last committer to this section of the code to investigate. Thank you very much. -- James E Keenan (jkeenan@cpan.org)
To: perl5-porters [...] perl.org
Subject: Re: [perl #128607] POD: sysseek
From: Zefram <zefram [...] fysh.org>
Date: Tue, 12 Jul 2016 20:49:42 +0100
Download (untitled) / with headers
text/plain 815b
via RT wrote: Show quoted text
> Note the in bytes: even if the filehandle has been set to operate > on characters (for example by using the ":encoding(utf8)" I/O > layer), "tell" will return byte offsets, not character offsets > (because implementing that would render "sysseek" unacceptably > slow). > >Where it says "tell" I think it should say "sysseek".
No, it really does mean "tell", but the wording is a bit awkward. It's obviously been copied from the equivalent paragraph in the "seek" doc, and that seems to have been copied from the equivalent for "tell", where it fits rather better. Note that it's referring to a function *returning* a byte offset, which "tell" relevantly does. "sysseek" also returns an offset, but that isn't discussed (and so isn't relevant) until the last paragraph of this doc. -zefram
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 607b
On Tue Jul 12 02:56:05 2016, niczero@wow.com wrote: Show quoted text
> The POD for sysseek [perldoc -f sysseek] appears to me to have an > error. In the second stanza it says > > Note the in bytes: even if the filehandle has been set to operate > on characters (for example by using the ":encoding(utf8)" I/O > layer), "tell" will return byte offsets, not character offsets > (because implementing that would render "sysseek" unacceptably > slow). > > Where it says "tell" I think it should say "sysseek". I suspect > it shouldn't mention 'tell' at all, other than in the following > stanza.
I agree. Fixed in 6d451ee1.
From: Dan Collins <dcollinsn [...] gmail.com>
Subject: Re: [perl #128607] POD: sysseek
To: Perl RT Bug Tracker <perlbug-followup [...] perl.org>
Date: Tue, 12 Jul 2016 17:20:15 -0400
Download (untitled) / with headers
text/plain 872b
Are you sure? Did you see Zefram's reply?

On Tue, Jul 12, 2016 at 4:58 PM, l.mai@web.de via RT <perlbug-followup@perl.org> wrote:
Show quoted text
On Tue Jul 12 02:56:05 2016, niczero@wow.com wrote:
> The POD for sysseek [perldoc -f sysseek] appears to me to have an
> error.  In the second stanza it says
>
> Note the in bytes: even if the filehandle has been set to operate
> on characters (for example by using the ":encoding(utf8)" I/O
> layer), "tell" will return byte offsets, not character offsets
> (because implementing that would render "sysseek" unacceptably
> slow).
>
> Where it says "tell" I think it should say "sysseek".  I suspect
> it shouldn't mention 'tell' at all, other than in the following
> stanza.

I agree. Fixed in 6d451ee1.

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=128607

From: Aristotle Pagaltzis <pagaltzis [...] gmx.de>
To: perl5-porters [...] perl.org
Subject: Re: [perl #128607] POD: sysseek
Date: Wed, 13 Jul 2016 05:21:22 +0200
Download (untitled) / with headers
text/plain 781b
* l.mai@web.de via RT <perlbug-followup@perl.org> [2016-07-12 23:00]: Show quoted text
> I agree. Fixed in 6d451ee1.
I don’t like this edit. I propose to instead change all 3 instances of that paragraph in perlfunc to the following: Note the emphasis on bytes: even if the filehandle has been set to operate on characters (for example using the C<:encoding(utf8)> I/O layer), the L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>, L<C<tell>|/tell FILEHANDLE>, and L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> family of functions use byte offsets, not character offsets, because seeking to a character offset would be very slow in a UTF-8 file. Pushed to ap/seektell so people can look at how the result looks&feels. Regards, -- Aristotle Pagaltzis // <http://plasmasturm.org/>
Date: Wed, 13 Jul 2016 14:01:05 +0100
Subject: Re: [perl #128607] POD: sysseek
To: perl5-porters [...] perl.org
From: Zefram <zefram [...] fysh.org>
Download (untitled) / with headers
text/plain 186b
Aristotle Pagaltzis wrote: Show quoted text
> I propose to instead change all 3 instances of >that paragraph in perlfunc to the following:
I like this proposed version. -zefram
Date: Wed, 13 Jul 2016 16:08:19 +0200
To: perl5-porters [...] perl.org
From: Sawyer X <xsawyerx [...] gmail.com>
Subject: Re: [perl #128607] POD: sysseek
Download (untitled) / with headers
text/plain 319b
On 07/13/2016 05:21 AM, Aristotle Pagaltzis wrote: Show quoted text
> * l.mai@web.de via RT <perlbug-followup@perl.org> [2016-07-12 23:00]:
>> I agree. Fixed in 6d451ee1.
> I don’t like this edit. I propose to instead change all 3 instances of > that paragraph in perlfunc to the following:
I think this phrasing is much clearer.
From: Aristotle Pagaltzis <pagaltzis [...] gmx.de>
Subject: Re: [perl #128607] POD: sysseek
To: perl5-porters [...] perl.org
Date: Wed, 13 Jul 2016 17:02:35 +0200
Download (untitled) / with headers
text/plain 211b
* Aristotle Pagaltzis <pagaltzis@gmx.de> [2016-07-13 05:24]: Show quoted text
> Pushed to ap/seektell so people can look at how the result looks&feels.
Now in blead as 01f0ef6b2ef087bcb4c6dc352861e0ed728c3ecb (and preceding).
Download (untitled) / with headers
text/plain 313b
Thank you for filing this report. You have helped make Perl better. With the release today of Perl 5.26.0, this and 210 other issues have been resolved. Perl 5.26.0 may be downloaded via: https://metacpan.org/release/XSAWYERX/perl-5.26.0 If you find that the problem persists, feel free to reopen this ticket.


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org