docs: `fs.write()` variables are not clear
The docs for fs.write()
state:
offset and length determine the part of the buffer to be written.
offset
is clear, but one must assume that length
has the same meaning as per buffer.slice(offset, length)
, i.e. that length
is not relative to offset
, but rather an absolute index into buffer as is expected (e.g. string.slice(offset, length)
). Therefore, if one wanted to write 5 bytes from offset 12 at position 1 in the file, one would use offset=12
, length=12+5
.
... (err, written, buffer) where written specifies how many bytes were written from buffer.
This is not clear.
I would probably guess that written
is a quantity number, i.e. if the first call to fs.write()
returned written=2
, then I would think that a count of 2 bytes had been written. I would therefore expect that fs.write(fd, buffer, offset=12, length=17, position=1)
would return written=5
if everything was written out, and less than 5
if a partial write occurred.
What actually happens is that written=17
when the write is fully written out. This is very surprising. Furthermore, if written
now represents an absolute index, is it an absolute index into the source buffer or an absolute index into the target file? If it is an absolute index into the target file, is it relative to position
or not? It seems that written
is actually then an absolute index relative to the source buffer
?
Why is buffer
returned in the write callback? Is this the same buffer I passed, or a slice? The docs should also make that clear.