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 | pub use crate::maybe_polyfill::io::{IoSlice, IoSliceMut}; |
9 | |
10 | #[cfg (linux_kernel)] |
11 | pub use backend::io::types::ReadWriteFlags; |
12 | |
13 | /// `read(fd, buf)`—Reads from a stream. |
14 | /// |
15 | /// # References |
16 | /// - [POSIX] |
17 | /// - [Linux] |
18 | /// - [Apple] |
19 | /// - [FreeBSD] |
20 | /// - [NetBSD] |
21 | /// - [OpenBSD] |
22 | /// - [DragonFly BSD] |
23 | /// - [illumos] |
24 | /// - [glibc] |
25 | /// |
26 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html |
27 | /// [Linux]: https://man7.org/linux/man-pages/man2/read.2.html |
28 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/read.2.html |
29 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=read&sektion=2 |
30 | /// [NetBSD]: https://man.netbsd.org/read.2 |
31 | /// [OpenBSD]: https://man.openbsd.org/read.2 |
32 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=read§ion=2 |
33 | /// [illumos]: https://illumos.org/man/2/read |
34 | /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/I_002fO-Primitives.html#index-reading-from-a-file-descriptor |
35 | #[inline ] |
36 | pub fn read<Fd: AsFd>(fd: Fd, buf: &mut [u8]) -> io::Result<usize> { |
37 | backend::io::syscalls::read(fd.as_fd(), buf) |
38 | } |
39 | |
40 | /// `write(fd, buf)`—Writes to a stream. |
41 | /// |
42 | /// # References |
43 | /// - [POSIX] |
44 | /// - [Linux] |
45 | /// - [Apple] |
46 | /// - [FreeBSD] |
47 | /// - [NetBSD] |
48 | /// - [OpenBSD] |
49 | /// - [DragonFly BSD] |
50 | /// - [illumos] |
51 | /// - [glibc] |
52 | /// |
53 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html |
54 | /// [Linux]: https://man7.org/linux/man-pages/man2/write.2.html |
55 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/write.2.html |
56 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=write&sektion=2 |
57 | /// [NetBSD]: https://man.netbsd.org/write.2 |
58 | /// [OpenBSD]: https://man.openbsd.org/write.2 |
59 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=write§ion=2 |
60 | /// [illumos]: https://illumos.org/man/2/write |
61 | /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/I_002fO-Primitives.html#index-writing-to-a-file-descriptor |
62 | #[inline ] |
63 | pub fn write<Fd: AsFd>(fd: Fd, buf: &[u8]) -> io::Result<usize> { |
64 | backend::io::syscalls::write(fd.as_fd(), buf) |
65 | } |
66 | |
67 | /// `pread(fd, buf, offset)`—Reads from a file at a given position. |
68 | /// |
69 | /// # References |
70 | /// - [POSIX] |
71 | /// - [Linux] |
72 | /// - [Apple] |
73 | /// - [FreeBSD] |
74 | /// - [NetBSD] |
75 | /// - [OpenBSD] |
76 | /// - [DragonFly BSD] |
77 | /// - [illumos] |
78 | /// |
79 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pread.html |
80 | /// [Linux]: https://man7.org/linux/man-pages/man2/pread.2.html |
81 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pread.2.html |
82 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pread&sektion=2 |
83 | /// [NetBSD]: https://man.netbsd.org/pread.2 |
84 | /// [OpenBSD]: https://man.openbsd.org/pread.2 |
85 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pread§ion=2 |
86 | /// [illumos]: https://illumos.org/man/2/pread |
87 | #[inline ] |
88 | pub fn pread<Fd: AsFd>(fd: Fd, buf: &mut [u8], offset: u64) -> io::Result<usize> { |
89 | backend::io::syscalls::pread(fd.as_fd(), buf, pos:offset) |
90 | } |
91 | |
92 | /// `pwrite(fd, bufs)`—Writes to a file at a given position. |
93 | /// |
94 | /// Contrary to POSIX, on many popular platforms including Linux and FreeBSD, |
95 | /// if the file is opened in append mode, this ignores the offset appends the |
96 | /// data to the end of the file. |
97 | /// |
98 | /// # References |
99 | /// - [POSIX] |
100 | /// - [Linux] |
101 | /// - [Apple] |
102 | /// - [FreeBSD] |
103 | /// - [NetBSD] |
104 | /// - [OpenBSD] |
105 | /// - [DragonFly BSD] |
106 | /// - [illumos] |
107 | /// |
108 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pwrite.html |
109 | /// [Linux]: https://man7.org/linux/man-pages/man2/pwrite.2.html |
110 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pwrite.2.html |
111 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pwrite&sektion=2 |
112 | /// [NetBSD]: https://man.netbsd.org/pwrite.2 |
113 | /// [OpenBSD]: https://man.openbsd.org/pwrite.2 |
114 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pwrite§ion=2 |
115 | /// [illumos]: https://illumos.org/man/2/pwrite |
116 | #[inline ] |
117 | pub fn pwrite<Fd: AsFd>(fd: Fd, buf: &[u8], offset: u64) -> io::Result<usize> { |
118 | backend::io::syscalls::pwrite(fd.as_fd(), buf, pos:offset) |
119 | } |
120 | |
121 | /// `readv(fd, bufs)`—Reads from a stream into multiple buffers. |
122 | /// |
123 | /// # References |
124 | /// - [POSIX] |
125 | /// - [Linux] |
126 | /// - [Apple] |
127 | /// - [FreeBSD] |
128 | /// - [NetBSD] |
129 | /// - [OpenBSD] |
130 | /// - [DragonFly BSD] |
131 | /// - [illumos] |
132 | /// |
133 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/readv.html |
134 | /// [Linux]: https://man7.org/linux/man-pages/man2/readv.2.html |
135 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/readv.2.html |
136 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=readv&sektion=2 |
137 | /// [NetBSD]: https://man.netbsd.org/readv.2 |
138 | /// [OpenBSD]: https://man.openbsd.org/readv.2 |
139 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=readv§ion=2 |
140 | /// [illumos]: https://illumos.org/man/2/readv |
141 | #[cfg (not(target_os = "espidf" ))] |
142 | #[inline ] |
143 | pub fn readv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> { |
144 | backend::io::syscalls::readv(fd.as_fd(), bufs) |
145 | } |
146 | |
147 | /// `writev(fd, bufs)`—Writes to a stream from multiple buffers. |
148 | /// |
149 | /// # References |
150 | /// - [POSIX] |
151 | /// - [Linux] |
152 | /// - [Apple] |
153 | /// - [FreeBSD] |
154 | /// - [NetBSD] |
155 | /// - [OpenBSD] |
156 | /// - [DragonFly BSD] |
157 | /// - [illumos] |
158 | /// |
159 | /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/writev.html |
160 | /// [Linux]: https://man7.org/linux/man-pages/man2/writev.2.html |
161 | /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/writev.2.html |
162 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=writev&sektion=2 |
163 | /// [NetBSD]: https://man.netbsd.org/writev.2 |
164 | /// [OpenBSD]: https://man.openbsd.org/writev.2 |
165 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=writev§ion=2 |
166 | /// [illumos]: https://illumos.org/man/2/writev |
167 | #[cfg (not(target_os = "espidf" ))] |
168 | #[inline ] |
169 | pub fn writev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>]) -> io::Result<usize> { |
170 | backend::io::syscalls::writev(fd.as_fd(), bufs) |
171 | } |
172 | |
173 | /// `preadv(fd, bufs, offset)`—Reads from a file at a given position into |
174 | /// multiple buffers. |
175 | /// |
176 | /// # References |
177 | /// - [Linux] |
178 | /// - [FreeBSD] |
179 | /// - [NetBSD] |
180 | /// - [OpenBSD] |
181 | /// - [DragonFly BSD] |
182 | /// - [illumos] |
183 | /// |
184 | /// [Linux]: https://man7.org/linux/man-pages/man2/preadv.2.html |
185 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=preadv&sektion=2 |
186 | /// [NetBSD]: https://man.netbsd.org/preadv.2 |
187 | /// [OpenBSD]: https://man.openbsd.org/preadv.2 |
188 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=preadv§ion=2 |
189 | /// [illumos]: https://illumos.org/man/2/preadv |
190 | #[cfg (not(any( |
191 | target_os = "espidf" , |
192 | target_os = "haiku" , |
193 | target_os = "nto" , |
194 | target_os = "redox" , |
195 | target_os = "solaris" |
196 | )))] |
197 | #[inline ] |
198 | pub fn preadv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> { |
199 | backend::io::syscalls::preadv(fd.as_fd(), bufs, pos:offset) |
200 | } |
201 | |
202 | /// `pwritev(fd, bufs, offset)`—Writes to a file at a given position from |
203 | /// multiple buffers. |
204 | /// |
205 | /// Contrary to POSIX, on many popular platforms including Linux and FreeBSD, |
206 | /// if the file is opened in append mode, this ignores the offset appends the |
207 | /// data to the end of the file. |
208 | /// |
209 | /// # References |
210 | /// - [Linux] |
211 | /// - [FreeBSD] |
212 | /// - [NetBSD] |
213 | /// - [OpenBSD] |
214 | /// - [DragonFly BSD] |
215 | /// - [illumos] |
216 | /// |
217 | /// [Linux]: https://man7.org/linux/man-pages/man2/pwritev.2.html |
218 | /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pwritev&sektion=2 |
219 | /// [NetBSD]: https://man.netbsd.org/pwritev.2 |
220 | /// [OpenBSD]: https://man.openbsd.org/pwritev.2 |
221 | /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pwritev§ion=2 |
222 | /// [illumos]: https://illumos.org/man/2/pwritev |
223 | #[cfg (not(any( |
224 | target_os = "espidf" , |
225 | target_os = "haiku" , |
226 | target_os = "nto" , |
227 | target_os = "redox" , |
228 | target_os = "solaris" |
229 | )))] |
230 | #[inline ] |
231 | pub fn pwritev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> { |
232 | backend::io::syscalls::pwritev(fd.as_fd(), bufs, pos:offset) |
233 | } |
234 | |
235 | /// `preadv2(fd, bufs, offset, flags)`—Reads data, with several options. |
236 | /// |
237 | /// An `offset` of `u64::MAX` means to use and update the current file offset. |
238 | /// |
239 | /// # References |
240 | /// - [Linux] |
241 | /// |
242 | /// [Linux]: https://man7.org/linux/man-pages/man2/preadv2.2.html |
243 | #[cfg (linux_kernel)] |
244 | #[inline ] |
245 | pub fn preadv2<Fd: AsFd>( |
246 | fd: Fd, |
247 | bufs: &mut [IoSliceMut<'_>], |
248 | offset: u64, |
249 | flags: ReadWriteFlags, |
250 | ) -> io::Result<usize> { |
251 | backend::io::syscalls::preadv2(fd.as_fd(), bufs, pos:offset, flags) |
252 | } |
253 | |
254 | /// `pwritev2(fd, bufs, offset, flags)`—Writes data, with several options. |
255 | /// |
256 | /// An `offset` of `u64::MAX` means to use and update the current file offset. |
257 | /// |
258 | /// # References |
259 | /// - [Linux] |
260 | /// |
261 | /// [Linux]: https://man7.org/linux/man-pages/man2/pwritev2.2.html |
262 | #[cfg (linux_kernel)] |
263 | #[inline ] |
264 | pub fn pwritev2<Fd: AsFd>( |
265 | fd: Fd, |
266 | bufs: &[IoSlice<'_>], |
267 | offset: u64, |
268 | flags: ReadWriteFlags, |
269 | ) -> io::Result<usize> { |
270 | backend::io::syscalls::pwritev2(fd.as_fd(), bufs, pos:offset, flags) |
271 | } |
272 | |