In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/6d451ee1f92cfef80e4008928166bcdf90f6324a?hp=f38a07a3f84aecc3cae5ca05af09c3f48ee61ddc>
- Log ----------------------------------------------------------------- commit 6d451ee1f92cfef80e4008928166bcdf90f6324a Author: Lukas Mai <[email protected]> Date: Tue Jul 12 22:33:20 2016 +0200 perlfunc: clarify seek/sysseek documentation re byte offsets (RT #128607) - The perlfunc entries for seek/sysseek were talking about tell instead of themselves in the section on byte offsets. Fix that. - Rearrange the paragraphs in the sysseek entry to describe parameters first, return value second, then everything else. This way the "byte offsets" section can refer to the (previously described) return value. - Hyperlink the 'systell' example in the tell entry to the sysseek entry. ----------------------------------------------------------------------- Summary of changes: pod/perlfunc.pod | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 5c778f1..4f2d3a1 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -6650,8 +6650,8 @@ otherwise. Note the I<in bytes>: even if the filehandle has been set to operate on characters (for example by using the C<:encoding(utf8)> open -layer), L<C<tell>|/tell FILEHANDLE> will return byte offsets, not -character offsets (because implementing that would render +layer), L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> will take byte offsets, +not character offsets (because implementing that would render L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> and L<C<tell>|/tell FILEHANDLE> rather slow). @@ -8537,10 +8537,26 @@ for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it to the current position plus POSITION; and C<2> to set it to EOF plus POSITION, typically negative. +For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>, +and C<SEEK_END> (start of the file, current position, end of the file) +from the L<Fcntl> module. Use of the constants is also more portable +than relying on 0, 1, and 2. + +Returns the new position in bytes, or the undefined value on failure. A +position of zero is returned as the string C<"0 but true">; thus +L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> returns +true on success and false on failure, yet you can still easily determine +the new position. + +For example to define a C<systell> function: + + use Fcntl 'SEEK_CUR'; + sub systell { sysseek($_[0], 0, SEEK_CUR) } + Note the I<in bytes>: even if the filehandle has been set to operate on characters (for example by using the C<:encoding(utf8)> I/O layer), -L<C<tell>|/tell FILEHANDLE> will return byte offsets, not character -offsets (because implementing that would render +L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> will take and return byte +offsets, not character offsets (because implementing that would render L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> unacceptably slow). L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> bypasses normal @@ -8553,20 +8569,6 @@ L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>, L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> may cause confusion. -For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>, -and C<SEEK_END> (start of the file, current position, end of the file) -from the L<Fcntl> module. Use of the constants is also more portable -than relying on 0, 1, and 2. For example to define a "systell" function: - - use Fcntl 'SEEK_CUR'; - sub systell { sysseek($_[0], 0, SEEK_CUR) } - -Returns the new position, or the undefined value on failure. A position -of zero is returned as the string C<"0 but true">; thus -L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> returns -true on success and false on failure, yet you can still easily determine -the new position. - =item system LIST X<system> X<shell> @@ -8714,7 +8716,8 @@ like the STDIN depends on the operating system: it may return -1 or something else. L<C<tell>|/tell FILEHANDLE> on pipes, fifos, and sockets usually returns -1. -There is no C<systell> function. Use C<sysseek($fh, 0, 1)> for that. +There is no C<systell> function. Use +L<C<sysseek($fh, 0, 1)>|/sysseek FILEHANDLE,POSITION,WHENCE> for that. Do not use L<C<tell>|/tell FILEHANDLE> (or other buffered I/O operations) on a filehandle that has been manipulated by -- Perl5 Master Repository
