If the system call doesn't tell us what happened, then the Write method can't tell the caller what happened. So I'm not sure what we should document. "It would be nice if we reported this correctly but we can't promise?"

I think the intent is clear: Write should report the number of bytes that were actually written. But if we don't know, we don't know.

But if we don't know, we don't know.

Fair; if we don't know, then what do we report? Should the count returned by Write include all of the bytes that were attempted, or none? That's what I'm trying to document, I guess.

I see. I think none. While we don't know whether that is accurate, it seems more likely than all or some, I think.

Much of Go's writer implementations or wrappers expect reliable byte stream: errors are often assumed to imply that the writer is unusable past that point.

The returned count from a Read call is particularly meaningful since Read can return early without error. In contrast, a Write call is expected to block until the full buffer has been written.

For writer-as-stream cases, it's not clear how valuable the returned n value would be. For seekable writers, it may be useful for tracking file offset, though WriterAt is probably more useful in those cases.

Since we should consistently return some value for n, due to the previously discussed ambiguity, perhaps we should just return the number of bytes affirmatively reported as being successfully written (which may be less than the number of bytes actually received, such as in the case of a broken network connection).

In the original scenario listed, this may mean that we report 0 bytes written, since the underlying transport may be unable to distinguish the number of bytes received on the other side and because we're sending all 17 bytes at once (we certainly wouldn't be writing 1 byte at a time just to have byte-level failure precision). If, internally, we sent a batch of 16 bytes (e.g. due to framing), which succeeded, and then sent 1 byte, which failed, we would certainly return 16, since that number was affirmatively successful.

I think it would be more useful to document the semantics of specific errors than to try document the semantics of n independent of the error value.

If there are specific errors that always indicate an exact count of bytes written — or specific errors that always indicate an inexact count of bytes written — then it seems useful for callers who observe those specific errors to know those implications, but given the ambiguity in the io.Writer interface — and the fact that existing implementations may have interpreted it either way — in the absence of a specific error value that says otherwise (or documentation for a specific implementation of the Write method) I don't think the caller can safely assume anything about the number of bytes actually written.