Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

POD: sysseek #15438

Closed
p5pRT opened this issue Jul 12, 2016 · 14 comments
Closed

POD: sysseek #15438

p5pRT opened this issue Jul 12, 2016 · 14 comments

Comments

@p5pRT
Copy link

p5pRT commented Jul 12, 2016

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

Searchable as RT128607$

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From niczero@wow.com

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

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From @dcollinsn

Introduced in 9124316, I agree that this is a typo (copy/pasted from other docs that were also added in that commit).

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

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

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From @jkeenan

On Tue Jul 12 02​:56​:05 2016, niczero@​wow.com wrote​:

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)

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From zefram@fysh.org

via RT wrote​:

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

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From @mauke

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 6d451ee.

@p5pRT
Copy link
Author

p5pRT commented Jul 12, 2016

From @dcollinsn

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​:

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 6d451ee.

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

@p5pRT
Copy link
Author

p5pRT commented Jul 13, 2016

From @ap

* l.mai@​web.de via RT <perlbug-followup@​perl.org> [2016-07-12 23​:00]​:

I agree. Fixed in 6d451ee.

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/>

@p5pRT
Copy link
Author

p5pRT commented Jul 13, 2016

From zefram@fysh.org

Aristotle Pagaltzis wrote​:

                   I propose to instead change all 3 instances of

that paragraph in perlfunc to the following​:

I like this proposed version.

-zefram

@p5pRT
Copy link
Author

p5pRT commented Jul 13, 2016

From @xsawyerx

On 07/13/2016 05​:21 AM, Aristotle Pagaltzis wrote​:

* l.mai@​web.de via RT <perlbug-followup@​perl.org> [2016-07-12 23​:00]​:

I agree. Fixed in 6d451ee.
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.

@p5pRT
Copy link
Author

p5pRT commented Jul 13, 2016

From @ap

* Aristotle Pagaltzis <pagaltzis@​gmx.de> [2016-07-13 05​:24]​:

Pushed to ap/seektell so people can look at how the result looks&feels.

Now in blead as 01f0ef6 (and preceding).

@p5pRT
Copy link
Author

p5pRT commented Jul 13, 2016

@cpansprout - Status changed from 'open' to 'pending release'

@p5pRT
Copy link
Author

p5pRT commented May 30, 2017

From @khwilliamson

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.

@p5pRT
Copy link
Author

p5pRT commented May 30, 2017

@khwilliamson - Status changed from 'pending release' to 'resolved'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant