From 8a1dd51447072dc2045b6112746242c4e4faf52b Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Tue, 9 Aug 2005 17:32:16 +0000
Subject: [PATCH] Added LINUX NOTES on trickery performed by glibc when vector
 size     exceeds IOV_MAX. Formatting clean-ups.

---
 man2/readv.2 | 70 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 20 deletions(-)

diff --git a/man2/readv.2 b/man2/readv.2
index 76b7b085f..e99e3bf9e 100644
--- a/man2/readv.2
+++ b/man2/readv.2
@@ -36,7 +36,7 @@ readv, writev \- read or write data into multiple buffers
 .fi
 .SH DESCRIPTION
 The
-.B readv()
+.BR readv ()
 function reads
 .I count
 blocks from the file associated with the file descriptor
@@ -45,7 +45,7 @@ into the multiple buffers described by
 .IR vector .
 .PP
 The
-.B writev()
+.BR writev ()
 function writes at most
 .I count
 blocks described by
@@ -56,41 +56,40 @@ to the file associated with the file descriptor
 The pointer
 .I vector
 points to a
-.B struct iovec
+.I struct iovec
 defined in
-.B <sys/uio.h>
+.I <sys/uio.h>
 as
 .PP
 .br
+.in +0.25in
 .nf
-.in 10
 struct iovec {
-.in 14
-void *iov_base;   /* Starting address */
-size_t iov_len;   /* Number of bytes */
-.in 10
+    void *iov_base;   /* Starting address */
+    size_t iov_len;   /* Number of bytes */
 };
 .fi
+.in 0.25in
 .PP
 Buffers are processed in the order specified.
 .PP
 The
-.B readv()
+.BR readv ()
 function works just like
 .BR read (2)
 except that multiple buffers are filled.
 .PP
 The
-.B writev()
+.BR writev ()
 function works just like
 .BR write (2)
 except that multiple buffers are written out.
 .PP
 .SH "RETURN VALUE"
 On success, the
-.B readv()
+.BR readv ()
 function returns the number of bytes read; the
-.B writev()
+.BR writev ()
 function returns the number of bytes written.
 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 .SH ERRORS
@@ -98,30 +97,61 @@ The errors are as given for
 .BR read (2)
 and
 .BR write (2).
-Additionally the following error is defined.
+Additionally the following error is defined:
 .TP
 .B EINVAL
 The sum of the
 .I iov_len
 values overflows an
-.B ssize_t
+.I ssize_t
 value. Or,
-the vector count \fIcount\fR is zero or greater than \fBMAX_IOVEC\fR.
+the vector count \fIcount\fR is less than zero or greater than the
+permitted maximum.
 .SH "CONFORMING TO"
 4.4BSD (the
-.B readv
+.BR readv ()
 and
-.B writev
+.BR writev ()
 functions first appeared in 4.2BSD), Unix98, POSIX 1003.1-2001.
 Linux libc5 used \fBsize_t\fR as the type of the \fIcount\fR parameter,
 and \fBint\fP as return type for these functions.
 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 .\" (Says release.libc.)
+.SH "LINUX NOTES"
+SUSv3 allows an implementation to place a limit on the number of items
+that can be passed in
+.IR vector .
+An implementation can advertise its limit by defining
+.B IOV_MAX
+in
+.IR <limits.h>
+or at run time via the return value from
+.IR sysconf(_SC_IOV_MAX) .
+On Linux, the limit advertised by these mechanisms is 1024,
+which is the true kernel limit.
+However, the glibc wrapper functions do some extra work if
+they detect that the underlying kernel system call failed because this
+limit was exceeded.  In the case of
+.BR readv ()
+the wrapper function allocates a temporary buffer large enough 
+for all of the items specified by
+.IR vector ,
+passes that buffer in a call to 
+.BR read (),
+copies data from the buffer to the locations specified by the
+.I iov_base
+fields of the elements of 
+.IR vector ,
+and then frees the buffer.
+The wrapper function for
+.BR writev ()
+performs the analogous task using a temporary buffer and a call to
+.BR write ().
 .SH BUGS
 It is not advisable to mix calls to functions like
-.B readv()
+.BR readv ()
 or
-.BR writev() ,
+.BR writev (),
 which operate on file descriptors, with the functions from the stdio
 library; the results will be undefined and probably not what you want.
 .SH "SEE ALSO"