Better documentation for readn()

diff --git a/src/src/exim.c b/src/src/exim.c
index 574fd553096cb0b30aeeb6e5f0b1664e801eb906..f09b26902a3a7b77b818b741503f0501c3a870f9 100644 (file)
--- a/src/src/exim.c
+++ b/src/src/exim.c
@@ -5839,9 +5839,30 @@ exim_exit(EXIT_SUCCESS);   /* Never returns */
 return 0;                  /* To stop compiler warning */
 }
 
-/* This function read(2)s until we got all the data we *requested*, in
-contrast to read(2), which may return less. Do not use this function if you're not
-sure that all the data is available already, otherwise it may block!
+/*************************************************
+*          read as much as requested             *
+*************************************************/
+
+/* The syscall read(2) doesn't always returns as much as we want. For
+several reasons it might get less. (Not talking about signals, as syscalls
+are restartable). When reading from a network or pipe connection the sender
+might send in smaller chunks, with delays between these chunks. The read(2)
+may return such a chunk.
+
+The more the writer writes and the smaller the pipe between write and read is,
+the more we get the chance of reading leass than requested. (See bug 2130)
+
+This function read(2)s until we got all the data we *requested*.
+
+Note: This function may block. Use it only if you're sure about the
+amount of data you will get.
+
+Argument:
+  fd          the file descriptor to read from
+  buffer      pointer to a buffer of size len
+  len         the requested(!) amount of bytes
+
+Returns:      the amount of bytes read
 */
 ssize_t
 readn(int fd, void *buffer, size_t len)
@@ -5853,7 +5874,7 @@ readn(int fd, void *buffer, size_t len)
     {
     ssize_t got = read(fd, next, end - next);
 
-    /* I'm not sure if there are signals that can interrupt as,
+    /* I'm not sure if there are signals that can interrupt us,
     for now I assume the worst */
     if (got == -1 && errno == EINTR) continue;
     if (got <= 0) return next - buffer;