Version 3.4.0-236.0.dev

Merge c771931 into dev

sdk/lib/io/file.dart

@@ -144,13 +144,14 @@ class FileLock {
 /// ```dart
 /// import 'dart:io';
 ///
-/// void main() {
+/// void main() async {
 ///   var file = File('file.txt');
 ///   var sink = file.openWrite();
 ///   sink.write('FILE ACCESSED ${DateTime.now()}\n');
+///   await sink.flush();
 ///
 ///   // Close the IOSink to free system resources.
-///   sink.close();
+///   await sink.close();
 /// }
 /// ```
 /// ## The use of asynchronous methods
@@ -497,8 +498,21 @@ abstract interface class File implements FileSystemEntity {
   /// to the pipe when it is opened, then [Stream.listen] will wait until
   /// a writer opens the pipe.
   ///
-  /// Any errors opening or reading the file will appear as error events in
-  /// the returned [Stream].
+  /// An error opening or reading the file will appear as a
+  /// [FileSystemException] error event on the returned [Stream], after which
+  /// the [Stream] is closed. For example:
+  ///
+  /// ```dart
+  /// // This example will print the "Error reading file" message and the
+  /// // `await for` loop will complete normally, without seeing any data
+  /// // events.
+  /// final stream = File('does-not-exist')
+  ///     .openRead()
+  ///     .handleError((e) => print('Error reading file: $e'));
+  /// await for (final data in stream) {
+  ///   print(data);
+  /// }
+  /// ```
   Stream<List<int>> openRead([int? start, int? end]);
 
   /// Creates a new independent [IOSink] for the file.
@@ -520,6 +534,38 @@ abstract interface class File implements FileSystemEntity {
   /// The returned [IOSink] does not transform newline characters (`"\n"`) to
   /// the platform's conventional line ending (e.g. `"\r\n"` on Windows). Write
   /// a [Platform.lineTerminator] if a platform-specific line ending is needed.
+  ///
+  /// If an error occurs while opening or writing to the file, the [IOSink.done]
+  /// [IOSink.flush], and [IOSink.close] futures will all complete with a
+  /// [FileSystemException]. You must handle errors from the [IOSink.done]
+  /// future or the error will be uncaught.
+  ///
+  /// For example, [FutureExtensions.ignore] the [IOSink.done] error and
+  /// remember to `await` the [IOSink.flush] and [IOSink.close] calls within a
+  /// `try`/`catch`:
+  ///
+  /// ```dart
+  /// final sink = File('/tmp').openWrite(); // Can't write to /tmp
+  /// sink.done.ignore();
+  /// sink.write("This is a test");
+  /// try {
+  ///   // If one of these isn't awaited, then errors will pass silently!
+  ///   await sink.flush();
+  ///   await sink.close();
+  /// } on FileSystemException catch (e) {
+  ///   print('Error writing file: $e');
+  /// }
+  /// ```
+  ///
+  /// To handle errors asynchronously outside of the context of [IOSink.flush]
+  /// and [IOSink.close], you can [Future.catchError] the [IOSink.done].
+  ///
+  /// ```dart
+  /// final sink = File('/tmp').openWrite(); // Can't write to /tmp
+  /// sink.done.catchError((e) {
+  ///  // Handle the error.
+  /// });
+  /// ```
   IOSink openWrite({FileMode mode = FileMode.write, Encoding encoding = utf8});
 
   /// Reads the entire file contents as a list of bytes.
@@ -1104,7 +1150,8 @@ abstract interface class ReadPipe implements Stream<List<int>> {}
 /// ```dart
 /// final pipe = await Pipe.create();
 /// pipe.write.add("Hello World!".codeUnits);
-/// pipe.write.close();
+/// await pipe.write.flush();
+/// await pipe.write.close();
 /// ```
 abstract interface class WritePipe implements IOSink {}
 
@@ -1124,7 +1171,8 @@ abstract interface class WritePipe implements IOSink {}
 ///     <ResourceHandle>[ResourceHandle.fromReadPipe(pipe.read)])
 /// ], 'Hello'.codeUnits);
 /// pipe.write.add('Hello over pipe!'.codeUnits);
-/// pipe.write.close();
+/// await pipe.write.flush();
+/// await pipe.write.close();
 /// ```
 abstract interface class Pipe {
   /// The read end of the [Pipe].

tools/VERSION

@@ -27,5 +27,5 @@ CHANNEL dev
 MAJOR 3
 MINOR 4
 PATCH 0
-PRERELEASE 235
+PRERELEASE 236
 PRERELEASE_PATCH 0