Mention $! vs $^E in pod/perlport.pod

Since 5.24, it has been deprecated to check $! after a Winsock function;
one such use $^E instead. However, since we do not have a deprecation
warning for this, we cannot set an EOL version of this deprecation.
As such, it just gets mentioned in perlport, and this will be the
only deprecation without an EOL version.

1 files changed, 23 insertions, 0 deletions

diff --git a/pod/perlport.pod b/pod/perlport.pod
index e8376033ac..c03e279be4 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -984,6 +984,29 @@ The very portable L<C<POSIX::uname()>|POSIX/C<uname>> will work too:
     c:\> perl -MPOSIX -we "print join '|', uname"
     Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
 
+Errors set by Winsock functions are now put directly into C<$^E>,
+and the relevant C<WSAE*> error codes are now exported from the
+L<Errno> and L<POSIX> modules for testing this against.
+
+The previous behavior of putting the errors (converted to POSIX-style
+C<E*> error codes since Perl 5.20.0) into C<$!> was buggy due to
+the non-equivalence of like-named Winsock and POSIX error constants,
+a relationship between which has unfortunately been established
+in one way or another since Perl 5.8.0.
+
+The new behavior provides a much more robust solution for checking
+Winsock errors in portable software without accidentally matching
+POSIX tests that were intended for other OSes and may have different
+meanings for Winsock.
+
+The old behavior is currently retained, warts and all, for backwards
+compatibility, but users are encouraged to change any code that
+tests C<$!> against C<E*> constants for Winsock errors to instead
+test C<$^E> against C<WSAE*> constants.  After a suitable deprecation
+period, which started with Perl 5.24, the old behavior may be
+removed, leaving C<$!> unchanged after Winsock function calls, to
+avoid any possible confusion over which error variable to check.
+
 Also see:
 
 =over 4