write.2: RETURN VALUE: clarify details of partial write and

write.2: RETURN VALUE: clarify details of partial write and

As reported by Nadav Har'El in
https://bugzilla.kernel.org/show_bug.cgi?id=197961

    The write(2) manual page has this paragraph:

    "On  success,  the  number  of bytes written is returned
    (zero indicates nothing was written).  It is not an error
    if  this  number  is  smaller than the number of bytes
    requested; this may happen for example because the disk
    device was filled.  See also NOTES."

    I find a few problems with this paragraph:

    1. It's not clear what "See also NOTES." refers to (does it
       refer to anything?). What in the NOTES is relevant here?

    2. The paragraph seems to suggest that write(2) of a
       non-empty buffer may sometimes return even 0 in case of an
       error like the device being filled. I think this is wrong
       - if there was an error after already writing some number
       of bytes, this non-zero number is returned. But if there's
       an error before writing any bytes, -1 will be returned
       (and the error reason in errno) - 0 will not be returned
       unless the given count is 0 (that case is explained in the
       following paragraph).

    3. The paragraph doesn't explain what a user should do
       after a short write (i.e., write(2) returning less than
       count). How would the user know why there was an error, or
       if there even was one? I think users should be told what
       to do next because this information is part of how to use
       this API correctly. I think users should be told to retry
       the rest of the write (i.e., write(fd, buf+ret, count-ret)
       and this will either succeed in writing some more data if
       the error reason was solved, or the second write will
       return -1 and the error reason in errno.

Reported-by: Nadav Har'El <nyh@math.technion.ac.il>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>