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.
Hey Nadav, I am really interested in working on this issue but since I am novice to open source, I don't know how to go about it. Can you please help me with this?
Hello Nadav, Thanks for the report. I agree with al of your points. I've rewritten the text as: On success, the number of bytes written is returned. On error, -1 is returned, and errno is set to indicate the cause of the error. Note that a successful write() may transfer fewer than count bytes. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked write() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another write() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full). Closing this bug. Please reopen if you think anything is still missing. Thanks, Michael