diff options
Diffstat (limited to 'manual/llio.texi')
| -rw-r--r-- | manual/llio.texi | 412 |
1 files changed, 201 insertions, 211 deletions
diff --git a/manual/llio.texi b/manual/llio.texi index 10ad546723..ff88805369 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -654,210 +654,6 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a @code{pwrite} and so transparently replaces the 32 bit interface. @end deftypefun -@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) -@standards{BSD, sys/uio.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux 3.2 for all architectures but microblaze -@c (which was added on 3.15). The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pread, and it is now a syscall on all -@c targets. - -This function is similar to the @code{readv} function, with the difference -it adds an extra @var{offset} parameter of type @code{off_t} similar to -@code{pread}. The data is written to the file starting at position -@var{offset}. The position of the file descriptor itself is not affected -by the operation. The value is the same as before the call. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{preadv} function is in fact @code{preadv64} and the type -@code{off_t} has 64 bits, which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is a count of bytes (@emph{not} buffers) read, @math{0} -indicating end-of-file, or @math{-1} indicating an error. The possible -errors are the same as in @code{readv} and @code{pread}. -@end deftypefun - -@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) -@standards{BSD, unistd.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux 3.2 for all architectures but microblaze -@c (which was added on 3.15). The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pread64, and it is now a syscall on all -@c targets. - -This function is similar to the @code{preadv} function with the difference -is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t}. It makes it possible on 32 bit machines to address -files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The -file descriptor @code{filedes} must be opened using @code{open64} since -otherwise the large offsets possible with @code{off64_t} will lead to -errors with a descriptor in small file mode. - -When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is actually available under the name -@code{preadv} and so transparently replaces the 32 bit interface. -@end deftypefun - -@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) -@standards{BSD, sys/uio.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux 3.2 for all architectures but microblaze -@c (which was added on 3.15). The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pwrite, and it is now a syscall on all -@c targets. - -This function is similar to the @code{writev} function, with the difference -it adds an extra @var{offset} parameter of type @code{off_t} similar to -@code{pwrite}. The data is written to the file starting at position -@var{offset}. The position of the file descriptor itself is not affected -by the operation. The value is the same as before the call. - -However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite} -appends data to the end of the file, regardless of the value of -@code{offset}. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{pwritev} function is in fact @code{pwritev64} and the type -@code{off_t} has 64 bits, which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is a count of bytes (@emph{not} buffers) written, @math{0} -indicating end-of-file, or @math{-1} indicating an error. The possible -errors are the same as in @code{writev} and @code{pwrite}. -@end deftypefun - -@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) -@standards{BSD, unistd.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux 3.2 for all architectures but microblaze -@c (which was added on 3.15). The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pwrite64, and it is now a syscall on all -@c targets. - -This function is similar to the @code{pwritev} function with the difference -is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t}. It makes it possible on 32 bit machines to address -files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The -file descriptor @code{filedes} must be opened using @code{open64} since -otherwise the large offsets possible with @code{off64_t} will lead to -errors with a descriptor in small file mode. - -When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is actually available under the name -@code{pwritev} and so transparently replaces the 32 bit interface. -@end deftypefun - -@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) -@standards{GNU, sys/uio.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls preadv. - -This function is similar to the @code{preadv} function, with the difference -it adds an extra @var{flags} parameter of type @code{int}. The supported -@var{flags} are dependent of the underlying system. For Linux it supports: - -@vtable @code -@item RWF_HIPRI -High priority request. This adds a flag that tells the file system that -this is a high priority request for which it is worth to poll the hardware. -The flag is purely advisory and can be ignored if not supported. The -@var{fd} must be opened using @code{O_DIRECT}. - -@item RWF_DSYNC -Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag. - -@item RWF_SYNC -Per-IO synchronization as if the file was opened with @code{O_SYNC} flag. - -@item RWF_NOWAIT -Use nonblocking mode for this operation; that is, this call to @code{preadv2} -will fail and set @code{errno} to @code{EAGAIN} if the operation would block. -@end vtable - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{preadv2} function is in fact @code{preadv64v2} and the type -@code{off_t} has 64 bits, which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is a count of bytes (@emph{not} buffers) read, @math{0} -indicating end-of-file, or @math{-1} indicating an error. The possible -errors are the same as in @code{preadv} with the addition of: - -@table @code - -@item EOPNOTSUPP - -@c The default sysdeps/posix code will return it for any flags value -@c different than 0. -An unsupported @var{flags} was used. - -@end table - -@end deftypefun - -@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) -@standards{GNU, unistd.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls preadv. - -This function is similar to the @code{preadv2} function with the difference -is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t}. It makes it possible on 32 bit machines to address -files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The -file descriptor @code{filedes} must be opened using @code{open64} since -otherwise the large offsets possible with @code{off64_t} will lead to -errors with a descriptor in small file mode. - -When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is actually available under the name -@code{preadv2} and so transparently replaces the 32 bit interface. -@end deftypefun - - -@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) -@standards{GNU, sys/uio.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pwritev. - -This function is similar to the @code{pwritev} function, with the difference -it adds an extra @var{flags} parameter of type @code{int}. The supported -@var{flags} are dependent of the underlying system and for Linux it supports -the same ones as for @code{preadv2}. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{pwritev2} function is in fact @code{pwritev64v2} and the type -@code{off_t} has 64 bits, which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is a count of bytes (@emph{not} buffers) write, @math{0} -indicating end-of-file, or @math{-1} indicating an error. The possible -errors are the same as in @code{preadv2}. -@end deftypefun - -@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) -@standards{GNU, unistd.h} -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation -@c is also MT-Safe since it calls pwritev. - -This function is similar to the @code{pwritev2} function with the difference -is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t}. It makes it possible on 32 bit machines to address -files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The -file descriptor @code{filedes} must be opened using @code{open64} since -otherwise the large offsets possible with @code{off64_t} will lead to -errors with a descriptor in small file mode. - -When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is actually available under the name -@code{pwritev2} and so transparently replaces the 32 bit interface. -@end deftypefun - - @node File Position Primitive @section Setting the File Position of a Descriptor @@ -1354,14 +1150,208 @@ error. The possible errors are the same as in @code{write}. @end deftypefun -@c Note - I haven't read this anywhere. I surmised it from my knowledge -@c of computer science. Thus, there could be subtleties I'm missing. +@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) +@standards{BSD, sys/uio.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux 3.2 for all architectures but microblaze +@c (which was added on 3.15). The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pread, and it is now a syscall on all +@c targets. + +This function is similar to the @code{readv} function, with the difference +it adds an extra @var{offset} parameter of type @code{off_t} similar to +@code{pread}. The data is written to the file starting at position +@var{offset}. The position of the file descriptor itself is not affected +by the operation. The value is the same as before the call. + +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{preadv} function is in fact @code{preadv64} and the type +@code{off_t} has 64 bits, which makes it possible to handle files up to +@twoexp{63} bytes in length. + +The return value is a count of bytes (@emph{not} buffers) read, @math{0} +indicating end-of-file, or @math{-1} indicating an error. The possible +errors are the same as in @code{readv} and @code{pread}. +@end deftypefun + +@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) +@standards{BSD, unistd.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux 3.2 for all architectures but microblaze +@c (which was added on 3.15). The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pread64, and it is now a syscall on all +@c targets. + +This function is similar to the @code{preadv} function with the difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t}. It makes it possible on 32 bit machines to address +files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a +32 bit machine this function is actually available under the name +@code{preadv} and so transparently replaces the 32 bit interface. +@end deftypefun + +@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}) +@standards{BSD, sys/uio.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux 3.2 for all architectures but microblaze +@c (which was added on 3.15). The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pwrite, and it is now a syscall on all +@c targets. + +This function is similar to the @code{writev} function, with the difference +it adds an extra @var{offset} parameter of type @code{off_t} similar to +@code{pwrite}. The data is written to the file starting at position +@var{offset}. The position of the file descriptor itself is not affected +by the operation. The value is the same as before the call. + +However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite} +appends data to the end of the file, regardless of the value of +@code{offset}. + +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{pwritev} function is in fact @code{pwritev64} and the type +@code{off_t} has 64 bits, which makes it possible to handle files up to +@twoexp{63} bytes in length. + +The return value is a count of bytes (@emph{not} buffers) written, @math{0} +indicating end-of-file, or @math{-1} indicating an error. The possible +errors are the same as in @code{writev} and @code{pwrite}. +@end deftypefun + +@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}) +@standards{BSD, unistd.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux 3.2 for all architectures but microblaze +@c (which was added on 3.15). The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pwrite64, and it is now a syscall on all +@c targets. + +This function is similar to the @code{pwritev} function with the difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t}. It makes it possible on 32 bit machines to address +files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a +32 bit machine this function is actually available under the name +@code{pwritev} and so transparently replaces the 32 bit interface. +@end deftypefun + +@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) +@standards{GNU, sys/uio.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls preadv. + +This function is similar to the @code{preadv} function, with the difference +it adds an extra @var{flags} parameter of type @code{int}. The supported +@var{flags} are dependent of the underlying system. For Linux it supports: + +@vtable @code +@item RWF_HIPRI +High priority request. This adds a flag that tells the file system that +this is a high priority request for which it is worth to poll the hardware. +The flag is purely advisory and can be ignored if not supported. The +@var{fd} must be opened using @code{O_DIRECT}. + +@item RWF_DSYNC +Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag. + +@item RWF_SYNC +Per-IO synchronization as if the file was opened with @code{O_SYNC} flag. + +@item RWF_NOWAIT +Use nonblocking mode for this operation; that is, this call to @code{preadv2} +will fail and set @code{errno} to @code{EAGAIN} if the operation would block. +@end vtable + +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{preadv2} function is in fact @code{preadv64v2} and the type +@code{off_t} has 64 bits, which makes it possible to handle files up to +@twoexp{63} bytes in length. + +The return value is a count of bytes (@emph{not} buffers) read, @math{0} +indicating end-of-file, or @math{-1} indicating an error. The possible +errors are the same as in @code{preadv} with the addition of: + +@table @code + +@item EOPNOTSUPP + +@c The default sysdeps/posix code will return it for any flags value +@c different than 0. +An unsupported @var{flags} was used. + +@end table + +@end deftypefun + +@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) +@standards{GNU, unistd.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls preadv. -Note that if the buffers are small (under about 1kB), high-level streams -may be easier to use than these functions. However, @code{readv} and -@code{writev} are more efficient when the individual buffers themselves -(as opposed to the total output), are large. In that case, a high-level -stream would not be able to cache the data efficiently. +This function is similar to the @code{preadv2} function with the difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t}. It makes it possible on 32 bit machines to address +files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a +32 bit machine this function is actually available under the name +@code{preadv2} and so transparently replaces the 32 bit interface. +@end deftypefun + + +@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags}) +@standards{GNU, sys/uio.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pwritev. + +This function is similar to the @code{pwritev} function, with the difference +it adds an extra @var{flags} parameter of type @code{int}. The supported +@var{flags} are dependent of the underlying system and for Linux it supports +the same ones as for @code{preadv2}. + +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the +@code{pwritev2} function is in fact @code{pwritev64v2} and the type +@code{off_t} has 64 bits, which makes it possible to handle files up to +@twoexp{63} bytes in length. + +The return value is a count of bytes (@emph{not} buffers) write, @math{0} +indicating end-of-file, or @math{-1} indicating an error. The possible +errors are the same as in @code{preadv2}. +@end deftypefun + +@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags}) +@standards{GNU, unistd.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation +@c is also MT-Safe since it calls pwritev. + +This function is similar to the @code{pwritev2} function with the difference +is that the @var{offset} parameter is of type @code{off64_t} instead of +@code{off_t}. It makes it possible on 32 bit machines to address +files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The +file descriptor @code{filedes} must be opened using @code{open64} since +otherwise the large offsets possible with @code{off64_t} will lead to +errors with a descriptor in small file mode. + +When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a +32 bit machine this function is actually available under the name +@code{pwritev2} and so transparently replaces the 32 bit interface. +@end deftypefun @node Memory-mapped I/O @section Memory-mapped I/O |