1 //! `read` and `write`, optionally positioned, optionally vectored
2
3 use crate::{backend, io};
4 use backend::fd::AsFd;
5
6 // Declare `IoSlice` and `IoSliceMut`.
7 #[cfg(not(windows))]
8 #[cfg(not(feature = "std"))]
9 pub use backend::io::io_slice::{IoSlice, IoSliceMut};
10 #[cfg(not(windows))]
11 #[cfg(feature = "std")]
12 pub use std::io::{IoSlice, IoSliceMut};
13
14 #[cfg(any(target_os = "android", target_os = "linux"))]
15 pub use backend::io::types::ReadWriteFlags;
16
17 /// `read(fd, buf)`—Reads from a stream.
18 ///
19 /// # References
20 /// - [POSIX]
21 /// - [Linux]
22 /// - [Apple]
23 ///
24 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html
25 /// [Linux]: https://man7.org/linux/man-pages/man2/read.2.html
26 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/read.2.html
27 #[inline]
read<Fd: AsFd>(fd: Fd, buf: &mut [u8]) -> io::Result<usize>28 pub fn read<Fd: AsFd>(fd: Fd, buf: &mut [u8]) -> io::Result<usize> {
29 backend::io::syscalls::read(fd.as_fd(), buf)
30 }
31
32 /// `write(fd, buf)`—Writes to a stream.
33 ///
34 /// # References
35 /// - [POSIX]
36 /// - [Linux]
37 /// - [Apple]
38 ///
39 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html
40 /// [Linux]: https://man7.org/linux/man-pages/man2/write.2.html
41 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/write.2.html
42 #[inline]
write<Fd: AsFd>(fd: Fd, buf: &[u8]) -> io::Result<usize>43 pub fn write<Fd: AsFd>(fd: Fd, buf: &[u8]) -> io::Result<usize> {
44 backend::io::syscalls::write(fd.as_fd(), buf)
45 }
46
47 /// `pread(fd, buf, offset)`—Reads from a file at a given position.
48 ///
49 /// # References
50 /// - [POSIX]
51 /// - [Linux]
52 /// - [Apple]
53 ///
54 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pread.html
55 /// [Linux]: https://man7.org/linux/man-pages/man2/pread.2.html
56 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pread.2.html
57 #[inline]
pread<Fd: AsFd>(fd: Fd, buf: &mut [u8], offset: u64) -> io::Result<usize>58 pub fn pread<Fd: AsFd>(fd: Fd, buf: &mut [u8], offset: u64) -> io::Result<usize> {
59 backend::io::syscalls::pread(fd.as_fd(), buf, offset)
60 }
61
62 /// `pwrite(fd, bufs)`—Writes to a file at a given position.
63 ///
64 /// Contrary to POSIX, on many popular platforms including Linux and FreeBSD,
65 /// if the file is opened in append mode, this ignores the offset appends the
66 /// data to the end of the file.
67 ///
68 /// # References
69 /// - [POSIX]
70 /// - [Linux]
71 /// - [Apple]
72 ///
73 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pwrite.html
74 /// [Linux]: https://man7.org/linux/man-pages/man2/pwrite.2.html
75 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pwrite.2.html
76 #[inline]
pwrite<Fd: AsFd>(fd: Fd, buf: &[u8], offset: u64) -> io::Result<usize>77 pub fn pwrite<Fd: AsFd>(fd: Fd, buf: &[u8], offset: u64) -> io::Result<usize> {
78 backend::io::syscalls::pwrite(fd.as_fd(), buf, offset)
79 }
80
81 /// `readv(fd, bufs)`—Reads from a stream into multiple buffers.
82 ///
83 /// # References
84 /// - [POSIX]
85 /// - [Linux]
86 /// - [Apple]
87 ///
88 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/readv.html
89 /// [Linux]: https://man7.org/linux/man-pages/man2/readv.2.html
90 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/readv.2.html
91 #[inline]
readv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize>92 pub fn readv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
93 backend::io::syscalls::readv(fd.as_fd(), bufs)
94 }
95
96 /// `writev(fd, bufs)`—Writes to a stream from multiple buffers.
97 ///
98 /// # References
99 /// - [POSIX]
100 /// - [Linux]
101 /// - [Apple]
102 ///
103 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/writev.html
104 /// [Linux]: https://man7.org/linux/man-pages/man2/writev.2.html
105 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/writev.2.html
106 #[inline]
writev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>]) -> io::Result<usize>107 pub fn writev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
108 backend::io::syscalls::writev(fd.as_fd(), bufs)
109 }
110
111 /// `preadv(fd, bufs, offset)`—Reads from a file at a given position into
112 /// multiple buffers.
113 ///
114 /// # References
115 /// - [Linux]
116 ///
117 /// [Linux]: https://man7.org/linux/man-pages/man2/preadv.2.html
118 #[cfg(not(any(target_os = "haiku", target_os = "redox", target_os = "solaris")))]
119 #[inline]
preadv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize>120 pub fn preadv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
121 backend::io::syscalls::preadv(fd.as_fd(), bufs, offset)
122 }
123
124 /// `pwritev(fd, bufs, offset)`—Writes to a file at a given position from
125 /// multiple buffers.
126 ///
127 /// Contrary to POSIX, on many popular platforms including Linux and FreeBSD,
128 /// if the file is opened in append mode, this ignores the offset appends the
129 /// data to the end of the file.
130 ///
131 /// # References
132 /// - [Linux]
133 ///
134 /// [Linux]: https://man7.org/linux/man-pages/man2/pwritev.2.html
135 #[cfg(not(any(target_os = "haiku", target_os = "redox", target_os = "solaris")))]
136 #[inline]
pwritev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize>137 pub fn pwritev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
138 backend::io::syscalls::pwritev(fd.as_fd(), bufs, offset)
139 }
140
141 /// `preadv2(fd, bufs, offset, flags)`—Reads data, with several options.
142 ///
143 /// An `offset` of `u64::MAX` means to use and update the current file offset.
144 ///
145 /// # References
146 /// - [Linux]
147 ///
148 /// [Linux]: https://man7.org/linux/man-pages/man2/preadv2.2.html
149 #[cfg(any(target_os = "android", target_os = "linux"))]
150 #[inline]
preadv2<Fd: AsFd>( fd: Fd, bufs: &mut [IoSliceMut<'_>], offset: u64, flags: ReadWriteFlags, ) -> io::Result<usize>151 pub fn preadv2<Fd: AsFd>(
152 fd: Fd,
153 bufs: &mut [IoSliceMut<'_>],
154 offset: u64,
155 flags: ReadWriteFlags,
156 ) -> io::Result<usize> {
157 backend::io::syscalls::preadv2(fd.as_fd(), bufs, offset, flags)
158 }
159
160 /// `pwritev2(fd, bufs, offset, flags)`—Writes data, with several options.
161 ///
162 /// An `offset` of `u64::MAX` means to use and update the current file offset.
163 ///
164 /// # References
165 /// - [Linux]
166 ///
167 /// [Linux]: https://man7.org/linux/man-pages/man2/pwritev2.2.html
168 #[cfg(any(target_os = "android", target_os = "linux"))]
169 #[inline]
pwritev2<Fd: AsFd>( fd: Fd, bufs: &[IoSlice<'_>], offset: u64, flags: ReadWriteFlags, ) -> io::Result<usize>170 pub fn pwritev2<Fd: AsFd>(
171 fd: Fd,
172 bufs: &[IoSlice<'_>],
173 offset: u64,
174 flags: ReadWriteFlags,
175 ) -> io::Result<usize> {
176 backend::io::syscalls::pwritev2(fd.as_fd(), bufs, offset, flags)
177 }
178