RandomAccessFile.writeByteSync documented return value is misleading

[jamesderlin]

The documentation for RandomAccessFile.writeByteSync states:

Synchronously writes a single byte to the file. Returns the number of bytes successfully written.

Throws a [FileSystemException] if the operation fails.

If it's writing a single byte, shouldn't the return value always be 1? It shouldn't ever return 0 since it is supposed to throw on failure.

But wait, if the write position is beyond the end of the file, writeByteSync apparently will extend the file, zero-filling the missing bytes. So maybe the return value isn't useless...

... except that the return value does not account for the file length extension. AFAICT, it always returns 1.

import 'dart:io';

void main() {
  final f = File('some_new_file');
  final h = f.openSync(mode: FileMode.write);
  print('Initial length: ${h.lengthSync()}'); // Prints: Initial length: 0
  h.setPositionSync(10);
  print('Length after setPosition: ${h.lengthSync()}'); // Prints: Length after setPosition: 0 
  final n = h.writeByteSync(0xFF);
  print('Wrote: $n bytes'); // Prints: 1
  h.closeSync();
}

Either the return value should be fixed or the documentation should just say "Always returns 1."

It also would be good to document that the file will be extended and zero-filled if the write position is out of bounds.

• Dart SDK: 2.8.4 on Linux

[sortie]

This is how the underlying operating system works. E.g. on Unix-like systems, the write(2) system call returns how many bytes of the requested buffer were used, but the system call may also extend the size of the file to the current position if it is beyond the file's current size. This is normal. There's no way to find out if this happened without race conditions, as other threads/processes may have extended / shrinked the file. The code is as it should be.

Then there's the question of whether the documentation is as it should be. I agree that this behavior isn't documented. But there are a lot of cases in dart:io where the functionality exposed is just a thin wrapper over the OS behavior and there's a lot of specific behavior that is well documented at that layer and duplicating it in the SDK wouldn't necessarily be practical or useful. I don't think this behavior is unexpected given the existing documentation and OS primitives, since the interface does return how many bytes were written of those you requested (which is 1).

But it's a valid point that this interface always return 1 on success and we can change the docuentation to say that. @zichangg Do you want to make that change?