Document how to use $SIG{ALRM} and alarm()

Subject: Re: reliable signal patch (was Re: Reliable signals)

On Tue, 26 Nov 1996 11:14:03 -0500 (EST), Kenneth Albanowski <kjahds@kjahds.com> said:
>
> Thus with restarting being the default, you can restart, if you want,
> by returning normally from the signal handler, or interrupt by dying.

Thanks, now I get it.  This is even inferred in perlipc(1).  Here's some
more explicit documentation.

p5p-msgid: <5898.849026569@eeyore.ibcinc.com>

1 files changed, 17 insertions, 0 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index df8d23fc1e..f153fe7af9 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -334,6 +334,23 @@ syscall() interface to access setitimer(2) if your system supports it,
 or else see L</select()> below.  It is not advised to intermix alarm() 
 and sleep() calls.
 
+If you want to use alarm() to time out a system call you need to use an
+eval/die pair. You can't rely on the alarm causing the system call to
+fail with $! set to EINTR because Perl sets up signal handlers to
+restart system calls on some systems.  Using eval/die always works.
+
+    eval {
+    	local $SIG{ALRM} = sub { die "alarm\n" };	# NB \n required
+	$nread = sysread SOCKET, $buffer, $size;
+    };
+    die if $@ and $@ ne "alarm\n";	# propagate errors
+    if ($@) {
+    	# timed out
+    }
+    else {
+    	# didn't
+    }
+
 =item atan2 Y,X
 
 Returns the arctangent of Y/X in the range -PI to PI.