Actually document the IO::Socket constructor's behaviour on failure, pointing out the $IO::Socket::errstr package var

3 files changed, 36 insertions, 0 deletions

diff --git a/dist/IO/lib/IO/Socket.pm b/dist/IO/lib/IO/Socket.pm
index 067fad8f19..7f298155b5 100644
--- a/dist/IO/lib/IO/Socket.pm
+++ b/dist/IO/lib/IO/Socket.pm
@@ -532,6 +532,18 @@ by default, be either C<AF_INET> or C<AF_UNIX>. Other domains can be used if a
 proper subclass for the domain family is registered. All other arguments will
 be passed to the C<configuration> method of the package for that domain.
 
+If the constructor fails it will return C<undef> and set the C<$errstr> package
+variable to contain an error message.
+
+    $sock = IO::Socket->new(...)
+        or die "Cannot create socket - $IO::Socket::errstr\n";
+
+For legacy reasons the error message is also set into the global C<$@>
+variable, and you may still find older code which looks here instead.
+
+    $sock = IO::Socket->new(...)
+        or die "Cannot create socket - $@\n";
+
 =head1 METHODS
 
 C<IO::Socket> inherits all methods from L<IO::Handle> and implements the
diff --git a/dist/IO/lib/IO/Socket/INET.pm b/dist/IO/lib/IO/Socket/INET.pm
index d194ee13e1..85065b9348 100644
--- a/dist/IO/lib/IO/Socket/INET.pm
+++ b/dist/IO/lib/IO/Socket/INET.pm
@@ -406,6 +406,18 @@ Examples:
                            Broadcast => 1 ) 
                        or die "Can't bind : $IO::Socket::errstr\n";
 
+If the constructor fails it will return C<undef> and set the
+C<$IO::Socket::errstr> package variable to contain an error message.
+
+    $sock = IO::Socket::INET->new(...)
+        or die "Cannot create socket - $IO::Socket::errstr\n";
+
+For legacy reasons the error message is also set into the global C<$@>
+variable, and you may still find older code which looks here instead.
+
+    $sock = IO::Socket::INET->new(...)
+        or die "Cannot create socket - $@\n";
+
 =back
 
 =head2 METHODS
diff --git a/dist/IO/lib/IO/Socket/UNIX.pm b/dist/IO/lib/IO/Socket/UNIX.pm
index 14d0b27a8c..42e86f7639 100644
--- a/dist/IO/lib/IO/Socket/UNIX.pm
+++ b/dist/IO/lib/IO/Socket/UNIX.pm
@@ -127,6 +127,18 @@ be a C<Peer> specification.
 
 If the C<Listen> argument is given, but false, the queue size will be set to 5.
 
+If the constructor fails it will return C<undef> and set the
+C<$IO::Socket::errstr> package variable to contain an error message.
+
+    $sock = IO::Socket::UNIX->new(...)
+        or die "Cannot create socket - $IO::Socket::errstr\n";
+
+For legacy reasons the error message is also set into the global C<$@>
+variable, and you may still find older code which looks here instead.
+
+    $sock = IO::Socket::UNIX->new(...)
+        or die "Cannot create socket - $@\n";
+
 =back
 
 =head1 METHODS