- * \param buf the buffer to write.
- * \param len the number of bytes of \a buf.
- *
- * EAGAIN is not considered an error condition. For example 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.
- *
- * \return Negative on errors, number of bytes written else.
+ * \param buf The buffer to write.
+ * \param len The number of bytes to write.
+ *
+ * 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.
+ *
+ * \return Negative on fatal errors, number of bytes written else. For blocking
+ * file descriptors this function returns either \a len or the error code of
+ * the fatal error that caused the last write call to fail. For nonblocking
+ * file descriptors there is a third possibility: A positive return value < \a
+ * len indicates that some bytes have been written but the next write would
+ * block.