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.