This is 5.8.0 RC2.

[p5sagit/p5-mst-13.2.git] / pod / perlipc.pod

diff --git a/pod/perlipc.pod b/pod/perlipc.pod
index 58e063f..c75fa95 100644 (file)
--- a/pod/perlipc.pod
+++ b/pod/perlipc.pod
@@ -168,6 +168,68 @@ module.  Lamentably, this is almost entirely undocumented, but
 the F<t/lib/posix.t> file from the Perl source distribution has some
 examples in it.
 
+=head2 Handling the SIGHUP Signal in Daemons
+
+A process that usually starts when the system boots and shuts down
+when the system is shut down is called a daemon (Disk And Execution
+MONitor). If a daemon process has a configuration file which is
+modified after the process has been started, there should be a way to
+tell that process to re-read its configuration file, without stopping
+the process. Many daemons provide this mechanism using the C<SIGHUP>
+signal handler. When you want to tell the daemon to re-read the file
+you simply send it the C<SIGHUP> signal.
+
+Not all platforms automatically reinstall their (native) signal
+handlers after a signal delivery.  This means that the handler works
+only the first time the signal is sent. The solution to this problem
+is to use C<POSIX> signal handlers if available, their behaviour
+is well-defined.
+
+The following example implements a simple daemon, which restarts
+itself every time the C<SIGHUP> signal is received. The actual code is
+located in the subroutine C<code()>, which simply prints some debug
+info to show that it works and should be replaced with the real code.
+
+  #!/usr/bin/perl -w
+  
+  use POSIX ();
+  use FindBin ();
+  use File::Basename ();
+  use File::Spec::Functions;
+  
+  $|=1;
+  
+  # make the daemon cross-platform, so exec always calls the script
+  # itself with the right path, no matter how the script was invoked.
+  my $script = File::Basename::basename($0);
+  my $SELF = catfile $FindBin::Bin, $script;
+  
+  # POSIX unmasks the sigprocmask properly
+  my $sigset = POSIX::SigSet->new();
+  my $action = POSIX::SigAction->new('sigHUP_handler',
+                                     $sigset,
+                                     &POSIX::SA_NODEFER);
+  POSIX::sigaction(&POSIX::SIGHUP, $action);
+  
+  sub sigHUP_handler {
+      print "got SIGHUP\n";
+      exec($SELF, @ARGV) or die "Couldn't restart: $!\n";
+  }
+  
+  code();
+  
+  sub code {
+      print "PID: $$\n";
+      print "ARGV: @ARGV\n";
+      my $c = 0;
+      while (++$c) {
+          sleep 2;
+          print "$c\n";
+      }
+  }
+  __END__
+
+
 =head1 Named Pipes
 
 A named pipe (often referred to as a FIFO) is an old Unix IPC
@@ -304,7 +366,7 @@ those signals (it does not do the C<wait>). Again the failure will
 look like a loop as the operating system will re-issue the signal as
 there are un-waited-for completed child processes.
 
-=back 4
+=back
 
 =head1 Using open() for IPC
 
@@ -508,6 +570,16 @@ And here's a safe pipe open for writing:
        # NOTREACHED
     }
 
+Since Perl 5.8.0, you can also use the list form of C<open> for pipes :
+the syntax
+
+    open KID_PS, "-|", "ps", "aux" or die $!;
+
+forks the ps(1) command (without spawning a shell, as there are more than
+three arguments to open()), and reads its standard output via the
+C<KID_PS> filehandle.  The corresponding syntax to read from command
+pipes (with C<"|-"> in place of C<"-|">) is also implemented.
+
 Note that these operations are full Unix forks, which means they may not be
 correctly implemented on alien systems.  Additionally, these are not true
 multithreading.  If you'd like to learn more about threading, see the