clarify what text 'warn' appends to a newline-less string

[perl5.git] / pod / perlfork.pod

diff --git a/pod/perlfork.pod b/pod/perlfork.pod
index d930e93..8f3b919 100644 (file)
--- 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.
@@ -11,7 +16,7 @@ call is available, Perl's fork() simply calls it.
 On some platforms such as Windows where the fork() system call is not
 available, Perl can be built to emulate fork() at the interpreter level.
 While the emulation is designed to be as compatible as possible with the
-real fork() at the the level of the Perl program, there are certain
+real fork() at the level of the Perl program, there are certain
 important differences that stem from the fact that all the pseudo child
 "processes" created this way live in the same real process as far as the
 operating system is concerned.
@@ -51,7 +56,7 @@ pseudo-processes are launched after others have been wait()-ed on.
 
 =item %ENV
 
-Each pseudo-process maintains its own virtual enviroment.  Modifications
+Each pseudo-process maintains its own virtual environment.  Modifications
 to %ENV affect the virtual environment, and are only visible within that
 pseudo-process, and in any processes (or pseudo-processes) launched from
 it.
@@ -95,7 +100,7 @@ waiting for after the exec().
 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
 
@@ -172,6 +177,13 @@ 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 systems manpages for more information
+on this.
+
 =item Forking pipe open() not yet implemented
 
 The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet
@@ -203,7 +215,6 @@ write to a forked child:
     else {
        # child
        while (<STDIN>) { print; }
-       close STDIN;
        exit(0);
     }
 
@@ -233,7 +244,6 @@ And this one reads from the child:
     else {
        # child
        print "pipe_from_fork\n";
-       close STDOUT;
        exit(0);
     }
 
@@ -282,6 +292,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