Posix rename

pkgs/io_file/example/io_file_example.dart

@@ -2,9 +2,9 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:io_file/io_file.dart';
+import 'package:io_file/posix_file_system.dart';
 
 void main() {
-  var awesome = Awesome();
-  print('awesome: ${awesome.isAwesome}');
+  // TODO: Create a better example.
+  PosixFileSystem().rename('foo.txt', 'bar.txt');
 }

pkgs/io_file/lib/io_file.dart

@@ -2,11 +2,4 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/// Support for doing something awesome.
-///
-/// More dartdocs go here.
-library;
-
-export 'src/io_file_base.dart';
-
-// TODO: Export any libraries intended for clients of this package.
+export 'src/file_system.dart';

pkgs/io_file/lib/src/io_file_base.dart → pkgs/io_file/lib/posix_file_system.dart

@@ -2,9 +2,4 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-// TODO: Put public facing types in this file.
-
-/// Checks if you are awesome. Spoiler: you are.
-class Awesome {
-  bool get isAwesome => true;
-}
+export 'src/posix_file_system.dart';

pkgs/io_file/lib/src/file_system.dart

@@ -0,0 +1,26 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// An abstract representation of a file system.
+base class FileSystem {
+  /// Renames, and possibly moves a file system object from one path to another.
+  ///
+  /// If `newPath` is a relative path, it is resolved against the current
+  /// working directory. This means that simply changing the name of a file,
+  /// but keeping it the original directory, requires creating a new complete
+  /// path with the new name at the end.
+  ///
+  /// TODO: add an example here.
+  ///
+  /// On some platforms, a rename operation cannot move a file between
+  /// different file systems. If that is the case, instead copy the file to the
+  /// new location and then remove the original.
+  ///
+  // If `newPath` identifies an existing file or link, that entity is removed
+  // first. If `newPath` identifies an existing directory, the operation
+  // fails and raises [PathExistsException].
+  void rename(String oldPath, String newPath) {
+    throw UnsupportedError('rename');
+  }
+}

pkgs/io_file/lib/src/posix_file_system.dart

@@ -0,0 +1,38 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io' as io;
+
+import 'package:stdlibc/stdlibc.dart' as stdlibc;
+
+import 'file_system.dart';
+
+Exception _getError(int errno, String message, String path) {
+  // TODO: In the long-term, do we need to avoid exceptions that are part of
+  // `dart:io`? Can we move those exceptions into a different namespace?
+  final osError = io.OSError(stdlibc.strerror(errno) ?? '', errno);
+
+  if (errno == stdlibc.EPERM || errno == stdlibc.EACCES) {
+    return io.PathAccessException(path, osError, message);
+  } else if (errno == stdlibc.EEXIST) {
+    return io.PathExistsException(path, osError, message);
+  } else if (errno == stdlibc.ENOENT) {
+    return io.PathNotFoundException(path, osError, message);
+  } else {
+    return io.FileSystemException(message, path, osError);
+  }
+}
+
+/// A [FileSystem] implementation for POSIX systems (e.g. Android, iOS, Linux,
+/// macOS).
+base class PosixFileSystem extends FileSystem {
+  @override
+  void rename(String oldPath, String newPath) {
+    // See https://pubs.opengroup.org/onlinepubs/000095399/functions/rename.html
+    if (stdlibc.rename(oldPath, newPath) != 0) {
+      final errno = stdlibc.errno;
+      throw _getError(errno, 'rename failed', oldPath);
+    }
+  }
+}

pkgs/io_file/pubspec.yaml

@@ -7,6 +7,13 @@ publish_to: none
 environment:
   sdk: ^3.7.0
 
+dependencies:
+  stdlibc:
+    git:
+      # Change this to a released version.
+      url: https://github.com/canonical/stdlibc.dart.git
+  win32: ^5.11.0
+
 dev_dependencies:
   dart_flutter_team_lints: ^3.4.0
   test: ^1.24.0

pkgs/io_file/test/io_file_test.dart → pkgs/io_file/test/file_system_test.dart

@@ -6,15 +6,9 @@ import 'package:io_file/io_file.dart';
 import 'package:test/test.dart';
 
 void main() {
-  group('A group of tests', () {
-    final awesome = Awesome();
-
-    setUp(() {
-      // Additional setup goes here.
-    });
-
-    test('First Test', () {
-      expect(awesome.isAwesome, isTrue);
+  group('FileSystem', () {
+    test('rename', () {
+      expect(() => FileSystem().rename('a', 'b'), throwsUnsupportedError);
     });
   });
 }

pkgs/io_file/test/rename_test.dart

@@ -0,0 +1,94 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+@TestOn('posix')
+library;
+
+import 'dart:io';
+import 'package:io_file/posix_file_system.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('move', () {
+    late String tmp;
+
+    setUp(
+      () => tmp = Directory.systemTemp.createTempSync('move').absolute.path,
+    );
+
+    tearDown(() => Directory(tmp).deleteSync(recursive: true));
+
+    // TODO: test with a very long path.
+
+    test('move file absolute path', () {
+      final path1 = '$tmp/file1';
+      final path2 = '$tmp/file2';
+
+      File(path1).writeAsStringSync('Hello World');
+      PosixFileSystem().rename(path1, path2);
+      expect(File(path1).existsSync(), isFalse);
+      expect(File(path2).existsSync(), isTrue);
+    });
+
+    test('move file to existing', () {
+      final path1 = '$tmp/file1';
+      final path2 = '$tmp/file2';
+
+      File(path1).writeAsStringSync('Hello World #1');
+      File(path2).writeAsStringSync('Hello World #2');
+      PosixFileSystem().rename(path1, path2);
+      expect(File(path1).existsSync(), isFalse);
+      expect(File(path2).readAsStringSync(), 'Hello World #1');
+    });
+
+    test('move directory absolute path', () {
+      final path1 = '$tmp/dir1';
+      final path2 = '$tmp/dir2';
+
+      Directory(path1).createSync(recursive: true);
+      PosixFileSystem().rename(path1, path2);
+      expect(Directory(path1).existsSync(), isFalse);
+      expect(Directory(path2).existsSync(), isTrue);
+    });
+
+    test('move non-existant', () {
+      final path1 = '$tmp/file1';
+      final path2 = '$tmp/file2';
+
+      expect(
+        () => PosixFileSystem().rename(path1, path2),
+        throwsA(
+          isA<PathNotFoundException>()
+              .having((e) => e.message, 'message', 'rename failed')
+              .having(
+                (e) => e.osError?.errorCode,
+                'errorCode',
+                2, // ENOENT
+              ),
+        ),
+      );
+    });
+
+    test('move to existant directory', () {
+      final path1 = '$tmp/file1';
+      final path2 = '$tmp/dir1';
+
+      File(path1).writeAsStringSync('Hello World');
+      Directory(path2).createSync(recursive: true);
+
+      expect(
+        () => PosixFileSystem().rename(path1, path2),
+        throwsA(
+          isA<FileSystemException>()
+              .having((e) => e.message, 'message', 'rename failed')
+              .having(
+                (e) => e.osError?.errorCode,
+                'errorCode',
+                21, // EISDIR
+              ),
+        ),
+      );
+    });
+  });
+}