| .\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) |
| .\" Merged readv.[23], 2002-10-17, aeb |
| .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and |
| .\" add more details. |
| .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() |
| .\" |
| .TH READV 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/uio.h> |
| .PP |
| .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
| .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
| .PP |
| .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , |
| .BI " off_t " offset ); |
| .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , |
| .BI " off_t " offset ); |
| .PP |
| .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , |
| .BI " off_t " offset ", int " flags ); |
| .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , |
| .BI " off_t " offset ", int " flags ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR preadv (), |
| .BR pwritev (): |
| .nf |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR readv () |
| system call reads |
| .I iovcnt |
| buffers from the file associated with the file descriptor |
| .I fd |
| into the buffers described by |
| .I iov |
| ("scatter input"). |
| .PP |
| The |
| .BR writev () |
| system call writes |
| .I iovcnt |
| buffers of data described by |
| .I iov |
| to the file associated with the file descriptor |
| .I fd |
| ("gather output"). |
| .PP |
| The pointer |
| .I iov |
| points to an array of |
| .I iovec |
| structures, |
| defined in |
| .I <sys/uio.h> |
| as: |
| .PP |
| .in +4n |
| .EX |
| struct iovec { |
| void *iov_base; /* Starting address */ |
| size_t iov_len; /* Number of bytes to transfer */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .BR readv () |
| system call works just like |
| .BR read (2) |
| except that multiple buffers are filled. |
| .PP |
| The |
| .BR writev () |
| system call works just like |
| .BR write (2) |
| except that multiple buffers are written out. |
| .PP |
| Buffers are processed in array order. |
| This means that |
| .BR readv () |
| completely fills |
| .I iov[0] |
| before proceeding to |
| .IR iov[1] , |
| and so on. |
| (If there is insufficient data, then not all buffers pointed to by |
| .I iov |
| may be filled.) |
| Similarly, |
| .BR writev () |
| writes out the entire contents of |
| .I iov[0] |
| before proceeding to |
| .IR iov[1] , |
| and so on. |
| .PP |
| The data transfers performed by |
| .BR readv () |
| and |
| .BR writev () |
| are atomic: the data written by |
| .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 |
| .BR writev () |
| is written as a single block that is not intermingled with output |
| from writes in other processes (but see |
| .BR pipe (7) |
| for an exception); |
| analogously, |
| .BR readv () |
| is guaranteed to read a contiguous block of data from the file, |
| regardless of read operations performed in other threads or processes |
| that have file descriptors referring to the same open file description |
| (see |
| .BR open (2)). |
| .SS preadv() and pwritev() |
| The |
| .BR preadv () |
| system call combines the functionality of |
| .BR readv () |
| and |
| .BR pread (2). |
| It performs the same task as |
| .BR readv (), |
| but adds a fourth argument, |
| .IR offset , |
| which specifies the file offset at which the input operation |
| is to be performed. |
| .PP |
| The |
| .BR pwritev () |
| system call combines the functionality of |
| .BR writev () |
| and |
| .BR pwrite (2). |
| It performs the same task as |
| .BR writev (), |
| but adds a fourth argument, |
| .IR offset , |
| which specifies the file offset at which the output operation |
| is to be performed. |
| .PP |
| The file offset is not changed by these system calls. |
| The file referred to by |
| .I fd |
| must be capable of seeking. |
| .SS preadv2() and pwritev2() |
| These system calls are similar to |
| .BR preadv () |
| and |
| .BR pwritev () |
| calls, but add a fifth argument, |
| .IR flags , |
| which modifies the behavior on a per-call basis. |
| .PP |
| Unlike |
| .BR preadv () |
| and |
| .BR pwritev (), |
| if the |
| .I offset |
| argument is \-1, then the current file offset is used and updated. |
| .PP |
| The |
| .I flags |
| argument contains a bitwise OR of zero or more of the following flags: |
| .TP |
| .BR RWF_DSYNC " (since Linux 4.7)" |
| .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 |
| Provide a per-write equivalent of the |
| .B O_DSYNC |
| .BR open (2) |
| flag. |
| This flag is meaningful only for |
| .BR pwritev2 (), |
| and its effect applies only to the data range written by the system call. |
| .TP |
| .BR RWF_HIPRI " (since Linux 4.6)" |
| High priority read/write. |
| Allows block-based filesystems to use polling of the device, |
| which provides lower latency, but may use additional resources. |
| (Currently, this feature is usable only on a file descriptor opened using the |
| .BR O_DIRECT |
| flag.) |
| .TP |
| .BR RWF_SYNC " (since Linux 4.7)" |
| .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 |
| Provide a per-write equivalent of the |
| .B O_SYNC |
| .BR open (2) |
| flag. |
| This flag is meaningful only for |
| .BR pwritev2 (), |
| and its effect applies only to the data range written by the system call. |
| .TP |
| .BR RWF_NOWAIT " (since Linux 4.14)" |
| .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 |
| .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 |
| Do not wait for data which is not immediately available. |
| If this flag is specified, the |
| .BR preadv2 () |
| system call will return instantly if it would have to read data from |
| the backing storage or wait for a lock. |
| If some data was successfully read, it will return the number of bytes read. |
| If no bytes were read, it will return \-1 and set |
| .IR errno |
| to |
| .BR EAGAIN . |
| Currently, this flag is meaningful only for |
| .BR preadv2 (). |
| .TP |
| .BR RWF_APPEND " (since Linux 4.16)" |
| .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb |
| Provide a per-write equivalent of the |
| .B O_APPEND |
| .BR open (2) |
| flag. |
| This flag is meaningful only for |
| .BR pwritev2 (), |
| and its effect applies only to the data range written by the system call. |
| The |
| .I offset |
| argument does not affect the write operation; |
| the data is always appended to the end of the file. |
| However, if the |
| .I offset |
| argument is \-1, the current file offset is updated. |
| .SH RETURN VALUE |
| On success, |
| .BR readv (), |
| .BR preadv (), |
| and |
| .BR preadv2 () |
| return the number of bytes read; |
| .BR writev (), |
| .BR pwritev (), |
| and |
| .BR pwritev2 () |
| return the number of bytes written. |
| .PP |
| Note that it is not an error for a successful call to transfer fewer bytes |
| than requested (see |
| .BR read (2) |
| and |
| .BR write (2)). |
| .PP |
| On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. |
| .SH ERRORS |
| The errors are as given for |
| .BR read (2) |
| and |
| .BR write (2). |
| Furthermore, |
| .BR preadv (), |
| .BR preadv2 (), |
| .BR pwritev (), |
| and |
| .BR pwritev2 () |
| can also fail for the same reasons as |
| .BR lseek (2). |
| Additionally, the following errors are defined: |
| .TP |
| .B EINVAL |
| The sum of the |
| .I iov_len |
| values overflows an |
| .I ssize_t |
| value. |
| .TP |
| .B EINVAL |
| The vector count, |
| .IR iovcnt , |
| is less than zero or greater than the permitted maximum. |
| .TP |
| .B EOPNOTSUPP |
| An unknown flag is specified in \fIflags\fP. |
| .SH VERSIONS |
| .BR preadv () |
| and |
| .BR pwritev () |
| first appeared in Linux 2.6.30; library support was added in glibc 2.10. |
| .PP |
| .BR preadv2 () |
| and |
| .BR pwritev2 () |
| first appeared in Linux 4.6. |
| Library support was added in glibc 2.26. |
| .SH CONFORMING TO |
| .BR readv (), |
| .BR writev (): |
| POSIX.1-2001, POSIX.1-2008, |
| 4.4BSD (these system calls first appeared in 4.2BSD). |
| .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, |
| .\" and \fIint\fP as the return type. |
| .\" The readv/writev system calls were buggy before Linux 1.3.40. |
| .\" (Says release.libc.) |
| .PP |
| .BR preadv (), |
| .BR pwritev (): |
| nonstandard, but present also on the modern BSDs. |
| .PP |
| .BR preadv2 (), |
| .BR pwritev2 (): |
| nonstandard Linux extension. |
| .SH NOTES |
| POSIX.1 allows an implementation to place a limit on |
| the number of items that can be passed in |
| .IR iov . |
| An implementation can advertise its limit by defining |
| .B IOV_MAX |
| in |
| .I <limits.h> |
| or at run time via the return value from |
| .IR sysconf(_SC_IOV_MAX) . |
| On modern Linux systems, the limit is 1024. |
| Back in Linux 2.0 days, this limit was 16. |
| .\" |
| .\" |
| .SS C library/kernel differences |
| The raw |
| .BR preadv () |
| and |
| .BR pwritev () |
| system calls have call signatures that differ slightly from that of the |
| corresponding GNU C library wrapper functions shown in the SYNOPSIS. |
| The final argument, |
| .IR offset , |
| is unpacked by the wrapper functions into two arguments in the system calls: |
| .PP |
| .BI " unsigned long " pos_l ", unsigned long " pos |
| .PP |
| These arguments contain, respectively, the low order and high order 32 bits of |
| .IR offset . |
| .SS Historical C library/kernel differences |
| To deal with the fact that |
| .B IOV_MAX |
| was so low on early versions of Linux, |
| the glibc wrapper functions for |
| .BR readv () |
| and |
| .BR writev () |
| did some extra work if they detected that the underlying kernel |
| system call failed because this limit was exceeded. |
| In the case of |
| .BR readv (), |
| the wrapper function allocated a temporary buffer large enough |
| for all of the items specified by |
| .IR iov , |
| passed that buffer in a call to |
| .BR read (2), |
| copied data from the buffer to the locations specified by the |
| .I iov_base |
| fields of the elements of |
| .IR iov , |
| and then freed the buffer. |
| The wrapper function for |
| .BR writev () |
| performed the analogous task using a temporary buffer and a call to |
| .BR write (2). |
| .PP |
| The need for this extra effort in the glibc wrapper functions |
| went away with Linux 2.2 and later. |
| However, glibc continued to provide this behavior until version 2.10. |
| Starting with glibc version 2.9, |
| the wrapper functions provide this behavior only if the library detects |
| that the system is running a Linux kernel older than version 2.6.18 |
| (an arbitrarily selected kernel version). |
| And since glibc 2.20 |
| (which requires a minimum Linux kernel version of 2.6.32), |
| the glibc wrapper functions always just directly invoke the system calls. |
| .SH EXAMPLES |
| The following code sample demonstrates the use of |
| .BR writev (): |
| .PP |
| .in +4n |
| .EX |
| char *str0 = "hello "; |
| char *str1 = "world\en"; |
| struct iovec iov[2]; |
| ssize_t nwritten; |
| |
| iov[0].iov_base = str0; |
| iov[0].iov_len = strlen(str0); |
| iov[1].iov_base = str1; |
| iov[1].iov_len = strlen(str1); |
| |
| nwritten = writev(STDOUT_FILENO, iov, 2); |
| .EE |
| .in |
| .SH SEE ALSO |
| .BR pread (2), |
| .BR read (2), |
| .BR write (2) |