LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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>
This commit is contained in:
Michael Kerrisk 2018-12-23 17:50:02 +01:00
parent acac1139a6
commit 3d335319e7
1 changed files with 20 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
man2/write.2
View File

@ -94,14 +94,27 @@ is greater than
the result is implementation-defined;
see NOTES for the upper limit on Linux.
.SH RETURN VALUE
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.
.PP
On success, the number of bytes written is returned.
On error, \-1 is returned, and \fIerrno\fP is set
appropriately.
to indicate the cause of the error.
.PP
Note that a successful
.BR write ()
may transfer fewer than
.I 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
.BR 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
.BR 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).
.PP
If \fIcount\fP is zero and
.I fd