diff options
Diffstat (limited to 'man2/readv.2')
| -rw-r--r-- | man2/readv.2 | 427 |
1 files changed, 0 insertions, 427 deletions
diff --git a/man2/readv.2 b/man2/readv.2 deleted file mode 100644 index c1295cd..0000000 --- a/man2/readv.2 +++ /dev/null @@ -1,427 +0,0 @@ -.\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com> -.\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" 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 2023-10-31 "Linux man-pages 6.7" -.SH NAME -readv, writev, preadv, pwritev, preadv2, pwritev2 \- -read or write data into multiple buffers -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/uio.h> -.P -.BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); -.BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); -.P -.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 ); -.P -.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 -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.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"). -.P -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"). -.P -The pointer -.I iov -points to an array of -.I iovec -structures, -described in -.BR iovec (3type). -.P -The -.BR readv () -system call works just like -.BR read (2) -except that multiple buffers are filled. -.P -The -.BR writev () -system call works just like -.BR write (2) -except that multiple buffers are written out. -.P -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. -.P -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; -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. -.P -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. -.P -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. -.P -Unlike -.BR preadv () -and -.BR pwritev (), -if the -.I offset -argument is \-1, then the current file offset is used and updated. -.P -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 -.B 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 -.I errno -to -.B EAGAIN -(but see -.BR BUGS ). -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. -.P -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)). -.P -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 -.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: -.P -.BI " unsigned long " pos_l ", unsigned long " pos -.P -These arguments contain, respectively, the low order and high order 32 bits of -.IR offset . -.SH STANDARDS -.TP -.BR readv () -.TQ -.BR writev () -POSIX.1-2008. -.TP -.BR preadv () -.TQ -.BR pwritev () -BSD. -.TP -.BR preadv2 () -.TQ -.BR pwritev2 () -Linux. -.SH HISTORY -.TP -.BR readv () -.TQ -.BR writev () -POSIX.1-2001, -4.4BSD (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.) -.P -.BR preadv (), -.BR pwritev (): -Linux 2.6.30, -glibc 2.10. -.P -.BR preadv2 (), -.BR pwritev2 (): -Linux 4.6, -glibc 2.26. -.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). -.P -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 glibc 2.10. -Starting with glibc 2.9, -the wrapper functions provide this behavior only if the library detects -that the system is running a Linux kernel older than Linux 2.6.18 -(an arbitrarily selected kernel version). -And since glibc 2.20 -(which requires a minimum of Linux 2.6.32), -the glibc wrapper functions always just directly invoke the system calls. -.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. -.\" -.\" -.SH BUGS -Linux 5.9 and Linux 5.10 have a bug where -.BR preadv2 () -with the -.B RWF_NOWAIT -flag may return 0 even when not at end of file. -.\" See -.\" <https://lore.kernel.org/linux-fsdevel/fea8b16d-5a69-40f9-b123-e84dcd6e8f2e@www.fastmail.com/T/#u> -.\" The bug was introduced in -.\" efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO -.\"and fixed in -.\" 06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig -.SH EXAMPLES -The following code sample demonstrates the use of -.BR writev (): -.P -.in +4n -.EX -char *str0 = "hello "; -char *str1 = "world\en"; -ssize_t nwritten; -struct iovec iov[2]; -\& -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) |