fd: Improve documentation of xwritev().

This is another essential helper which was poorly documented. In
particular the EINTR and short write cases were not covered, and it
was left open what a return value of zero means.

Omit the DCCP-specific part and the sentence which explains what
EAGAIN means.

diff --git a/fd.c b/fd.c
index 180032daa6d0f7bf11a63984480842b007c316c6..d0de66f41be6008c2d3be5afe6dae002fb06ceb5 100644 (file)
--- a/fd.c
+++ b/fd.c
@@ -37,26 +37,27 @@ int xrename(const char *oldpath, const char *newpath)
 }
 
 /**
- * Write an array of buffers to a file descriptor.
+ * Write an array of buffers, handling non-fatal errors.
  *
- * \param fd The file descriptor.
+ * \param fd The file descriptor to write to.
  * \param iov Pointer to one or more buffers.
  * \param iovcnt The number of buffers.
  *
- * EAGAIN/EWOULDBLOCK is not considered a fatal error condition. For example
- * DCCP CCID3 has a sending wait queue which fills up and is emptied
- * asynchronously. The EAGAIN case means that there is currently no space in
- * the wait queue, but this can change at any moment.
+ * EAGAIN, EWOULDBLOCK and EINTR are not considered error conditions. If a
+ * write operation fails with EAGAIN or EWOULDBLOCK, the number of bytes that
+ * have been written so far is returned. In the EINTR case the operation is
+ * retried. Short writes are handled by issuing a subsequent write operation
+ * for the remaining part.
  *
  * \return Negative on fatal errors, number of bytes written else.
  *
  * For blocking file descriptors, this function returns either the sum of all
- * buffer sizes, or the error code of the fatal error that caused the last
- * write call to fail.
+ * buffer sizes or a negative error code which indicates the fatal error that
+ * caused a write call to fail.
  *
- * For nonblocking file descriptors there is a third possibility: Any positive
- * return value less than the sum of the buffer sizes indicates that some bytes
- * have been written but the next write would block.
+ * For nonblocking file descriptors there is a third possibility: Any
+ * non-negative return value less than the sum of the buffer sizes indicates
+ * that a write operation returned EAGAIN/EWOULDBLOCK.
  *
  * \sa writev(2), \ref xwrite().
  */