POD: sysseek

[p5pRT]

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

Searchable as RT128607$

[p5pRT]

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]

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]

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

[p5pRT]

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]

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]

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]

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]

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]

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]

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]

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]

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

[p5pRT]

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]

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