diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2018-12-23 17:50:02 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2018-12-23 19:09:33 +0100 |
| commit | 3d335319e7bdb14d73d93fd5bf135eec6741d822 (patch) | |
| tree | 2ae763c5637055fb28177aa57854dee5ab70c2d6 /man2/write.2 | |
| parent | acac1139a661b144a6d82c33bc7e6b43a4a60c1c (diff) | |
| download | man-pages-3d335319e7bdb14d73d93fd5bf135eec6741d822.tar.gz | |
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>
Diffstat (limited to 'man2/write.2')
| -rw-r--r-- | man2/write.2 | 27 |
1 files changed, 20 insertions, 7 deletions
diff --git a/man2/write.2 b/man2/write.2 index d6e14aaf0a..5118a15500 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -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 |