X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/ee8c7f5465f003860e2347a2946abacac39bd9b9..12f3ad4ebe4097bd8c213e744ff27acdf4cbdc2d:/pod/perlfork.pod

diff --git a/pod/perlfork.pod b/pod/perlfork.pod
index 82ac689..709d053 100644
--- a/pod/perlfork.pod
+++ b/pod/perlfork.pod
@@ -4,6 +4,11 @@ perlfork - Perl's fork() emulation
 
 =head1 SYNOPSIS
 
+    NOTE:  As of the 5.8.0 release, fork() emulation has considerably
+    matured.  However, there are still a few known bugs and differences
+    from real fork() that might affect you.  See the "BUGS" and
+    "CAVEATS AND LIMITATIONS" sections below.
+
 Perl provides a fork() keyword that corresponds to the Unix system call
 of the same name.  On most Unix-like platforms where the fork() system
 call is available, Perl's fork() simply calls it.
@@ -32,7 +37,7 @@ thread that implements this child "process" as the pseudo-process.
 
 To the Perl program that called fork(), all this is designed to be
 transparent.  The parent returns from the fork() with a pseudo-process
-ID that can be subsequently used in any process manipulation functions;
+ID that can be subsequently used in any process-manipulation functions;
 the child returns from the fork() with a value of C<0> to signify that
 it is the child pseudo-process.
 
@@ -72,12 +77,24 @@ and return its status.
 
 =item kill()
 
-kill() can be used to terminate a pseudo-process by passing it the ID returned
-by fork().  This should not be used except under dire circumstances, because
-the operating system may not guarantee integrity of the process resources
-when a running thread is terminated.  Note that using kill() on a
-pseudo-process() may typically cause memory leaks, because the thread that
-implements the pseudo-process does not get a chance to clean up its resources.
+C<kill('KILL', ...)> can be used to terminate a pseudo-process by
+passing it the ID returned by fork().  This should not be used except
+under dire circumstances, because the operating system may not
+guarantee integrity of the process resources when a running thread is
+terminated.  Note that using C<kill('KILL', ...)> on a
+pseudo-process() may typically cause memory leaks, because the thread
+that implements the pseudo-process does not get a chance to clean up
+its resources.
+
+C<kill('TERM', ...)> can also be used on pseudo-processes, but the
+signal will not be delivered while the pseudo-process is blocked by a
+system call, e.g. waiting for a socket to connect, or trying to read
+from a socket with no data available.  Starting in Perl 5.14 the
+parent process will not wait for children to exit once they have been
+signalled with C<kill('TERM', ...)> to avoid deadlock during process
+exit.  You will have to explicitly call waitpid() to make sure the
+child has time to clean-up itself, but you are then also responsible
+that the child is not blocking on I/O either.
 
 =item exec()
 
@@ -90,12 +107,15 @@ manipulation functions applied to the ID returned by fork() will affect the
 waiting pseudo-process that called exec(), not the real process it is
 waiting for after the exec().
 
+When exec() is called inside a pseudo-process then DESTROY methods and
+END blocks will still be called after the external process returns.
+
 =item exit()
 
 exit() always exits just the executing pseudo-process, after automatically
 wait()-ing for any outstanding child pseudo-processes.  Note that this means
 that the process as a whole will not exit unless all running pseudo-processes
-have exited.
+have exited.  See below for some limitations with open filehandles.
 
 =item Open handles to files, directories and network sockets
 
@@ -129,11 +149,12 @@ to complete before they exit.  This means that the parent and every
 pseudo-child created by it that is also a pseudo-parent will only exit
 after their pseudo-children have exited.
 
-A way to mark a pseudo-processes as running detached from their parent (so
-that the parent would not have to wait() for them if it doesn't want to)
-will be provided in future.
+Starting with Perl 5.14 a parent will not wait() automatically
+for any child that has been signalled with C<sig('TERM', ...)>
+to avoid a deadlock in case the child is blocking on I/O and
+never receives the signal.
 
-=head2 CAVEATS AND LIMITATIONS
+=head1 CAVEATS AND LIMITATIONS
 
 =over 8
 
@@ -172,6 +193,26 @@ the seek position in the parent will change it in the child and vice-versa.
 One can avoid this by opening files that need distinct seek pointers
 separately in the child.
 
+On some operating systems, notably Solaris and Unixware, calling C<exit()>
+from a child process will flush and close open filehandles in the parent,
+thereby corrupting the filehandles.  On these systems, calling C<_exit()>
+is suggested instead.  C<_exit()> is available in Perl through the 
+C<POSIX> module.  Please consult your system's manpages for more information
+on this.
+
+=item Open directory handles
+
+Perl will completely read from all open directory handles until they
+reach the end of the stream.  It will then seekdir() back to the
+original location and all future readdir() requests will be fulfilled
+from the cache buffer.  That means that neither the directory handle held
+by the parent process nor the one held by the child process will see
+any changes made to the directory after the fork() call.
+
+Note that rewinddir() has a similar limitation on Windows and will not
+force readdir() to read the directory again either.  Only a newly
+opened directory handle will reflect changes to the directory.
+
 =item Forking pipe open() not yet implemented
 
 The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet
@@ -203,7 +244,6 @@ write to a forked child:
     else {
 	# child
 	while (<STDIN>) { print; }
-	close STDIN;
 	exit(0);
     }
 
@@ -233,7 +273,6 @@ And this one reads from the child:
     else {
 	# child
 	print "pipe_from_fork\n";
-	close STDOUT;
 	exit(0);
     }
 
@@ -282,6 +321,15 @@ representation for pseudo-process IDs will be implemented in future.
 
 =item *
 
+In certain cases, the OS-level handles created by the pipe(), socket(),
+and accept() operators are apparently not duplicated accurately in
+pseudo-processes.  This only happens in some situations, but where it
+does happen, it may result in deadlocks between the read and write ends
+of pipe handles, or inability to send or receive data across socket
+handles.
+
+=item *
+
 This document may be incomplete in some respects.
 
 =back