mention autoflush portability caveat

p4raw-id: //depot/perl@5703

3 files changed, 44 insertions, 5 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7bae55a802..e4930816e5 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1432,6 +1432,12 @@ program, passing it C<"surprise"> an argument.  The second version
 didn't--it tried to run a program literally called I<"echo surprise">,
 didn't find it, and set C<$?> to a non-zero value indicating failure.
 
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before the exec, but this may not be supported on some platforms
+(see L<perlport>).  To be safe, you may need to set C<$|> ($AUTOFLUSH
+in English) or call the C<autoflush()> method of C<IO::Handle> on any
+open handles in order to avoid lost output.
+
 Note that C<exec> will not call your C<END> blocks, nor will it call
 any C<DESTROY> methods in your objects.
 
@@ -1650,7 +1656,11 @@ fork(), great care has gone into making it extremely efficient (for
 example, using copy-on-write technology on data pages), making it the
 dominant paradigm for multitasking over the last few decades.
 
-All files opened for output are flushed before forking the child process.
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before forking the child process, but this may not be supported
+on some platforms (see L<perlport>).  To be safe, you may need to set
+C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
+C<IO::Handle> on any open handles in order to avoid duplicate output.
 
 If you C<fork> without ever waiting on your children, you will
 accumulate zombies.  On some systems, you can avoid this by setting
@@ -2753,8 +2763,13 @@ The following triples are more or less equivalent:
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
-NOTE: On any operation that may do a fork, all files opened for output
-are flushed before the fork is attempted.  On systems that support a
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>).  To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
+
+On systems that support a
 close-on-exec flag on files, the flag will be set for the newly opened
 file descriptor as determined by the value of $^F.  See L<perlvar/$^F>.
 
@@ -4910,7 +4925,11 @@ platforms).  If there are no shell metacharacters in the argument,
 it is split into words and passed directly to C<execvp>, which is
 more efficient.
 
-All files opened for output are flushed before attempting the exec().
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>).  To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
 
 The return value is the exit status of the program as
 returned by the C<wait> call.  To get the actual exit value divide by
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 5e4ce937fa..a81f7fe8b2 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1051,6 +1051,12 @@ multiple commands in a single line by separating them with the command
 separator character, if your shell supports that (e.g. C<;> on many Unix
 shells; C<&> on the Windows NT C<cmd> shell).
 
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before starting the child process, but this may not be supported
+on some platforms (see L<perlport>).  To be safe, you may need to set
+C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
+C<IO::Handle> on any open handles.
+
 Beware that some command shells may place restrictions on the length
 of the command line.  You must ensure your strings don't exceed this
 limit after any necessary interpolations.  See the platform-specific
diff --git a/pod/perlport.pod b/pod/perlport.pod
index 10723ee3a4..44b4ebed81 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -1287,6 +1287,9 @@ Not implemented. (S<Mac OS>)
 
 Implemented via Spawn. (VM/ESA)
 
+Does not automatically flush output handles on some platforms.
+(SunOS, Solaris, HP-UX)
+
 =item fcntl FILEHANDLE,FUNCTION,SCALAR
 
 Not implemented. (Win32, VMS)
@@ -1299,7 +1302,12 @@ Available only on Windows NT (not on Windows 95). (Win32)
 
 =item fork
 
-Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>, VOS, VM/ESA)
+Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VOS, VM/ESA)
+
+Emulated using multiple interpreters.  See L<perlfork>.  (Win32)
+
+Does not automatically flush output handles on some platforms.
+(SunOS, Solaris, HP-UX)
 
 =item getlogin
 
@@ -1502,6 +1510,9 @@ The C<|> variants are supported only if ToolServer is installed.
 
 open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
 
+Opening a process does not automatically flush output handles on some
+platforms.  (SunOS, Solaris, HP-UX)
+
 =item pipe READHANDLE,WRITEHANDLE
 
 Not implemented. (S<Mac OS>)
@@ -1618,6 +1629,9 @@ Far from being POSIX compliant.  Because there may be no underlying
 first token in its argument string.  Handles basic redirection
 ("<" or ">") on its own behalf. (MiNT)
 
+Does not automatically flush output handles on some platforms.
+(SunOS, Solaris, HP-UX)
+
 =item times
 
 Only the first entry returned is nonzero. (S<Mac OS>)