diff options
Diffstat (limited to 'man/man2/readv.2')
| -rw-r--r-- | man/man2/readv.2 | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/man/man2/readv.2 b/man/man2/readv.2 new file mode 100644 index 000000000..d39f2b9b9 --- /dev/null +++ b/man/man2/readv.2 @@ -0,0 +1,427 @@ +.\" 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 (date) "Linux man-pages (unreleased)" +.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) |