No, it means you think s/// or \G is broken, not pos(). But s/// and \G aren't broken.

Are you sure you know what I think? :^) I didn't say anything about "broken". I just say, that the function does not work as documented and propose to change the documentation to avoid the long arguments like this.

One more time. The perldoc -f pos states 'so assigning to "pos" will change that offset, and so will also influence the "\G" zero-width assertion in regular expressions'. In reality, when pos is used during matching it does not influence the "\G". Which means that the documentation is incorrect. If you believe, that pos does influence the \G during matching, then please provide a proof. If you just don't like the words that I've used to state this, then I don't think it makes sense to argue :)

Which means that the documentation is incorrect.

Here is the documentation, how would you change it?

Returns the offset of where the last "m//g" search left off for the variable in question ($_ is used when the variable is not specified). Note that 0 is a valid match offset. "undef" indicates that the search position is reset (usually due to match failure, but can also be because no match has yet been run on the scalar). "pos" directly accesses the location used by the regexp engine to store the offset, so assigning to "pos" will change that offset, and so will also influence the "\G" zero-width assertion in regular expressions. Because a failed "m//gc" match doesn't reset the offset, the return from "pos" won't change either in this case. See perlre and perlop.

Consider this with the sentence in bold above

$ perl -le"$_ = 123456; s/./warn pos; warn q,  ,, pos=0;/eg"
0 at -e line 1.
  0 at -e line 1.
1 at -e line 1.
  0 at -e line 1.
2 at -e line 1.
  0 at -e line 1.
3 at -e line 1.
  0 at -e line 1.
4 at -e line 1.
  0 at -e line 1.
5 at -e line 1.
  0 at -e line 1.
[download]

so the engine matches, then evaluates the code, then advances pos, and it doesn't care if your code changed pos in the meantime

Here is the documentation, how would you change it?

The change is fairly simple.

Returns the offset of where the last "m//g" search left off for the variable in question ($_ is used when the variable is not specified). Note that 0 is a valid match offset. "undef" indicates that the search position is reset (usually due to match failure, but can also be because no match has yet been run on the scalar). "pos" directly accesses the location used by the regexp engine to store the offset, so assigning to "pos" will change that offset, and so will influence the "\G" zero-width assertion next time when this string is matched against some regular expression. Note, it does not have any influence on the currently running match. Because a failed "m//gc" match doesn't reset the offset, the return from "pos" won't change either in this case. See perlre and perlop.