# HG changeset patch
# User Rik <rik@octave.org>
# Date 1513368077 28800
# Node ID c341ebb40ede6ef40a4e51ea92bd4fbd5d59b620
# Parent  3cd47be4fcbea96eac4f80301ff1c3c5dcd2d6b9# Parent  d400b09043dd414dcbccd312705ca8e84a2e11f5
maint: merge stable to default.

diff -r 3cd47be4fcbe -r c341ebb40ede libinterp/corefcn/file-io.cc
--- a/libinterp/corefcn/file-io.cc	Fri Dec 15 09:21:26 2017 -0800
+++ b/libinterp/corefcn/file-io.cc	Fri Dec 15 12:01:17 2017 -0800
@@ -532,7 +532,7 @@
 though writing to the same file through several different file ids may
 produce unexpected results.
 
-The possible values @samp{mode} may have are
+The possible values of @var{mode} are
 
 @table @asis
 @item @samp{r} (default)
@@ -557,11 +557,10 @@
 @end table
 
 Append a @qcode{"t"} to the mode string to open the file in text mode or a
-@qcode{"b"} to open in binary mode.  On Windows and Macintosh systems,
+@qcode{"b"} to open in binary mode.  On Windows systems,
 text mode reading and writing automatically converts linefeeds to the
 appropriate line end character for the system (carriage-return linefeed on
-Windows, carriage-return on Macintosh).  The default when no mode is
-specified is binary mode.
+Windows).  The default when no mode is specified is binary.
 
 Additionally, you may append a @qcode{"z"} to the mode string to open a
 gzipped file for reading or writing.  For this to be successful, you
@@ -587,6 +586,14 @@
 
 When opening a new file that does not yet exist, permissions will be set to
 @code{0666 - @var{umask}}.
+
+Compatibility Note: Octave opens files using buffered I/O.  Small writes are
+accumulated until an internal buffer is filled, and then everything is written
+in a single operation.  This is very efficient and improves performance.
+@sc{matlab}, however, opens files using flushed I/O where every write operation
+is immediately performed.  If the write operation must be performed immediately
+after data has been written then the write should be followed by a call to
+@code{fflush} to flush the internal buffer.
 @seealso{fclose, fgets, fgetl, fscanf, fread, fputs, fdisp, fprintf, fwrite, fskipl, fseek, frewind, ftell, feof, ferror, fclear, fflush, freport, umask}
 @end deftypefn */)
 {