Clarify the return values of pos, particularly 0 and undef, as

suggested by Stas Bekman

p4raw-id: //depot/perl@23550

1 files changed, 8 insertions, 3 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index c67560fb5b..5fde4b81af 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3828,9 +3828,14 @@ array in subroutines, just like C<shift>.
 =item pos
 
 Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified).  May be
-modified to change that offset.  Such modification will also influence
-the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
+in question (C<$_> is used when the variable is not specified).  Note that
+0 is a valid match offset, while C<undef> indicates that the search position
+is reset (usually due to match failure, but can also be because no match has
+yet been performed on the scalar). C<pos> directly accesses the location used
+by the regexp engine to store the offset, so assigning to C<pos> will change
+that offset, and so will also influence the C<\G> zero-width assertion in
+regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
+the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST