Skip to main content

std/sys/fd/
unix.rs

1#![unstable(reason = "not public", issue = "none", feature = "fd")]
2
3#[cfg(test)]
4mod tests;
5
6#[cfg(not(any(target_os = "linux", target_os = "android", target_os = "hurd")))]
7use libc::off_t as off64_t;
8#[cfg(any(target_os = "android", target_os = "linux", target_os = "hurd"))]
9use libc::off64_t;
10
11cfg_select! {
12    target_os = "vxworks" => {
13        // VxWorks does not have pread/pwrite.
14        // See <https://github.com/rust-lang/libc/issues/5328>.
15        pub unsafe fn pread64(
16            _fd: libc::c_int,
17            _buf: *mut libc::c_void,
18            _count: libc::size_t,
19            _offset: off64_t,
20        ) -> libc::ssize_t {
21            -1
22        }
23
24        pub unsafe fn pwrite64(
25            _fd: libc::c_int,
26            _buf: *const libc::c_void,
27            _count: libc::size_t,
28            _offset: off64_t,
29        ) -> libc::ssize_t {
30            -1
31        }
32    }
33    any(
34        all(target_os = "linux", not(target_env = "musl")),
35        target_os = "android",
36        target_os = "hurd"
37    ) => {
38        // Prefer explicit pread64 for 64-bit offset independently of libc
39        // #[cfg(gnu_file_offset_bits64)].
40        use libc::{pread64, pwrite64};
41    }
42    _ => {
43        use libc::{pread as pread64, pwrite as pwrite64};
44    }
45}
46
47use crate::cmp;
48use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut, Read};
49use crate::os::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
50#[cfg(all(target_os = "android", target_pointer_width = "64"))]
51use crate::sys::pal::weak::syscall;
52#[cfg(any(
53    all(target_os = "android", target_pointer_width = "32"),
54    all(target_vendor = "apple", not(all(target_os = "macos", target_arch = "aarch64")))
55))]
56use crate::sys::pal::weak::weak;
57use crate::sys::{AsInner, FromInner, IntoInner, cvt};
58
59#[derive(Debug)]
60pub struct FileDesc(OwnedFd);
61
62// The maximum read limit on most POSIX-like systems is `SSIZE_MAX`,
63// with the man page quoting that if the count of bytes to read is
64// greater than `SSIZE_MAX` the result is "unspecified".
65//
66// On Apple targets however, apparently the 64-bit libc is either buggy or
67// intentionally showing odd behavior by rejecting any read with a size
68// larger than INT_MAX.
69//
70// Meanwhile on QNX, reads/writes/sends larger than INT_MAX return the wrong
71// number of bytes written (eg, writing 2^31 bytes returns (2^64 - 2^31) instead
72// of the correct byte count).
73const READ_LIMIT: usize = cfg_select! {
74    any(target_vendor = "apple", target_os = "nto", target_os = "qnx") => libc::c_int::MAX as usize,
75    _ => libc::ssize_t::MAX as usize,
76};
77
78#[cfg(any(
79    target_os = "dragonfly",
80    target_os = "freebsd",
81    target_os = "netbsd",
82    target_os = "openbsd",
83    target_vendor = "apple",
84    target_os = "cygwin",
85))]
86const fn max_iov() -> usize {
87    libc::IOV_MAX as usize
88}
89
90#[cfg(any(
91    target_os = "android",
92    target_os = "emscripten",
93    target_os = "linux",
94    target_os = "nto",
95    target_os = "qnx",
96))]
97const fn max_iov() -> usize {
98    libc::UIO_MAXIOV as usize
99}
100
101#[cfg(not(any(
102    target_os = "android",
103    target_os = "dragonfly",
104    target_os = "emscripten",
105    target_os = "espidf",
106    target_os = "freebsd",
107    target_os = "linux",
108    target_os = "netbsd",
109    target_os = "nuttx",
110    target_os = "nto",
111    target_os = "qnx",
112    target_os = "openbsd",
113    target_os = "horizon",
114    target_os = "vita",
115    target_vendor = "apple",
116    target_os = "cygwin",
117)))]
118const fn max_iov() -> usize {
119    16 // The minimum value required by POSIX.
120}
121
122impl FileDesc {
123    #[inline]
124    pub fn try_clone(&self) -> io::Result<Self> {
125        self.duplicate()
126    }
127
128    pub fn read(&self, buf: &mut [u8]) -> io::Result<usize> {
129        let ret = cvt(unsafe {
130            libc::read(
131                self.as_raw_fd(),
132                buf.as_mut_ptr() as *mut libc::c_void,
133                cmp::min(buf.len(), READ_LIMIT),
134            )
135        })?;
136        Ok(ret as usize)
137    }
138
139    #[cfg(not(any(
140        target_os = "espidf",
141        target_os = "horizon",
142        target_os = "vita",
143        target_os = "nuttx"
144    )))]
145    pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
146        let ret = cvt(unsafe {
147            libc::readv(
148                self.as_raw_fd(),
149                bufs.as_mut_ptr() as *mut libc::iovec as *const libc::iovec,
150                cmp::min(bufs.len(), max_iov()) as libc::c_int,
151            )
152        })?;
153        Ok(ret as usize)
154    }
155
156    #[cfg(any(
157        target_os = "espidf",
158        target_os = "horizon",
159        target_os = "vita",
160        target_os = "nuttx"
161    ))]
162    pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
163        io::default_read_vectored(|b| self.read(b), bufs)
164    }
165
166    #[inline]
167    pub fn is_read_vectored(&self) -> bool {
168        cfg!(not(any(
169            target_os = "espidf",
170            target_os = "horizon",
171            target_os = "vita",
172            target_os = "nuttx",
173            target_os = "wasi",
174        )))
175    }
176
177    pub fn read_to_end(&self, buf: &mut Vec<u8>) -> io::Result<usize> {
178        let mut me = self;
179        (&mut me).read_to_end(buf)
180    }
181
182    pub fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
183        cvt(unsafe {
184            pread64(
185                self.as_raw_fd(),
186                buf.as_mut_ptr() as *mut libc::c_void,
187                cmp::min(buf.len(), READ_LIMIT),
188                offset as off64_t, // EINVAL if offset + count overflows
189            )
190        })
191        .map(|n| n as usize)
192    }
193
194    pub fn read_buf(&self, mut cursor: BorrowedCursor<'_, u8>) -> io::Result<()> {
195        // SAFETY: `cursor.as_mut()` starts with `cursor.capacity()` writable bytes
196        let ret = cvt(unsafe {
197            libc::read(
198                self.as_raw_fd(),
199                cursor.as_mut().as_mut_ptr().cast::<libc::c_void>(),
200                cmp::min(cursor.capacity(), READ_LIMIT),
201            )
202        })?;
203
204        // SAFETY: `ret` bytes were written to the initialized portion of the buffer
205        unsafe {
206            cursor.advance(ret as usize);
207        }
208        Ok(())
209    }
210
211    pub fn read_buf_at(&self, mut cursor: BorrowedCursor<'_, u8>, offset: u64) -> io::Result<()> {
212        // SAFETY: `cursor.as_mut()` starts with `cursor.capacity()` writable bytes
213        let ret = cvt(unsafe {
214            pread64(
215                self.as_raw_fd(),
216                cursor.as_mut().as_mut_ptr().cast::<libc::c_void>(),
217                cmp::min(cursor.capacity(), READ_LIMIT),
218                offset as off64_t, // EINVAL if offset + count overflows
219            )
220        })?;
221
222        // SAFETY: `ret` bytes were written to the initialized portion of the buffer
223        unsafe {
224            cursor.advance(ret as usize);
225        }
226        Ok(())
227    }
228
229    #[cfg(any(
230        target_os = "aix",
231        target_os = "dragonfly", // DragonFly 1.5
232        target_os = "emscripten",
233        target_os = "freebsd",
234        target_os = "fuchsia",
235        target_os = "hurd",
236        target_os = "illumos",
237        target_os = "linux",
238        target_os = "netbsd",
239        target_os = "openbsd", // OpenBSD 2.7
240        target_os = "l4re",
241        all(target_os = "macos", target_arch = "aarch64"),
242    ))]
243    pub fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
244        let ret = cvt(unsafe {
245            libc::preadv(
246                self.as_raw_fd(),
247                bufs.as_mut_ptr() as *mut libc::iovec as *const libc::iovec,
248                cmp::min(bufs.len(), max_iov()) as libc::c_int,
249                offset as _,
250            )
251        })?;
252        Ok(ret as usize)
253    }
254
255    #[cfg(not(any(
256        target_os = "aix",
257        target_os = "android",
258        target_os = "dragonfly",
259        target_os = "emscripten",
260        target_os = "freebsd",
261        target_os = "fuchsia",
262        target_os = "hurd",
263        target_os = "illumos",
264        target_os = "linux",
265        target_os = "netbsd",
266        target_os = "openbsd",
267        target_vendor = "apple",
268        target_os = "l4re",
269    )))]
270    pub fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
271        io::default_read_vectored(|b| self.read_at(b, offset), bufs)
272    }
273
274    // We support some old Android versions that do not have `preadv` in libc,
275    // so we use weak linkage and fallback to a direct syscall if not available.
276    //
277    // On 32-bit targets, we don't want to deal with weird ABI issues around
278    // passing 64-bits parameters to syscalls, so we fallback to the default
279    // implementation if `preadv` is not available.
280    #[cfg(all(target_os = "android", target_pointer_width = "64"))]
281    pub fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
282        syscall!(
283            fn preadv(
284                fd: libc::c_int,
285                iovec: *const libc::iovec,
286                n_iovec: libc::c_int,
287                offset: off64_t,
288            ) -> isize;
289        );
290
291        let ret = cvt(unsafe {
292            preadv(
293                self.as_raw_fd(),
294                bufs.as_mut_ptr() as *mut libc::iovec as *const libc::iovec,
295                cmp::min(bufs.len(), max_iov()) as libc::c_int,
296                offset as _,
297            )
298        })?;
299        Ok(ret as usize)
300    }
301
302    #[cfg(all(target_os = "android", target_pointer_width = "32"))]
303    pub fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
304        weak!(
305            fn preadv64(
306                fd: libc::c_int,
307                iovec: *const libc::iovec,
308                n_iovec: libc::c_int,
309                offset: off64_t,
310            ) -> isize;
311        );
312
313        match preadv64.get() {
314            Some(preadv) => {
315                let ret = cvt(unsafe {
316                    preadv(
317                        self.as_raw_fd(),
318                        bufs.as_mut_ptr() as *mut libc::iovec as *const libc::iovec,
319                        cmp::min(bufs.len(), max_iov()) as libc::c_int,
320                        offset as _,
321                    )
322                })?;
323                Ok(ret as usize)
324            }
325            None => io::default_read_vectored(|b| self.read_at(b, offset), bufs),
326        }
327    }
328
329    // We support old MacOS, iOS, watchOS, tvOS and visionOS. `preadv` was added in the following
330    // Apple OS versions:
331    // iOS 14.0
332    // tvOS 14.0
333    // macOS 11.0
334    // watchOS 7.0
335    //
336    // Since macOS 11.0 is also the first version with AArch64 support, we can
337    // `preadv` unconditionally there. But on all other targets we must use
338    // "weak" linking.
339    #[cfg(all(target_vendor = "apple", not(all(target_os = "macos", target_arch = "aarch64"))))]
340    pub fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
341        weak!(
342            fn preadv(
343                fd: libc::c_int,
344                iovec: *const libc::iovec,
345                n_iovec: libc::c_int,
346                offset: off64_t,
347            ) -> isize;
348        );
349
350        match preadv.get() {
351            Some(preadv) => {
352                let ret = cvt(unsafe {
353                    preadv(
354                        self.as_raw_fd(),
355                        bufs.as_mut_ptr() as *mut libc::iovec as *const libc::iovec,
356                        cmp::min(bufs.len(), max_iov()) as libc::c_int,
357                        offset as _,
358                    )
359                })?;
360                Ok(ret as usize)
361            }
362            None => io::default_read_vectored(|b| self.read_at(b, offset), bufs),
363        }
364    }
365
366    pub fn write(&self, buf: &[u8]) -> io::Result<usize> {
367        let ret = cvt(unsafe {
368            libc::write(
369                self.as_raw_fd(),
370                buf.as_ptr() as *const libc::c_void,
371                cmp::min(buf.len(), READ_LIMIT),
372            )
373        })?;
374        Ok(ret as usize)
375    }
376
377    #[cfg(not(any(
378        target_os = "espidf",
379        target_os = "horizon",
380        target_os = "vita",
381        target_os = "nuttx"
382    )))]
383    pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
384        let ret = cvt(unsafe {
385            libc::writev(
386                self.as_raw_fd(),
387                bufs.as_ptr() as *const libc::iovec,
388                cmp::min(bufs.len(), max_iov()) as libc::c_int,
389            )
390        })?;
391        Ok(ret as usize)
392    }
393
394    #[cfg(any(
395        target_os = "espidf",
396        target_os = "horizon",
397        target_os = "vita",
398        target_os = "nuttx"
399    ))]
400    pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
401        io::default_write_vectored(|b| self.write(b), bufs)
402    }
403
404    #[inline]
405    pub fn is_write_vectored(&self) -> bool {
406        cfg!(not(any(
407            target_os = "espidf",
408            target_os = "horizon",
409            target_os = "vita",
410            target_os = "nuttx",
411            target_os = "wasi",
412        )))
413    }
414
415    pub fn write_at(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
416        unsafe {
417            cvt(pwrite64(
418                self.as_raw_fd(),
419                buf.as_ptr() as *const libc::c_void,
420                cmp::min(buf.len(), READ_LIMIT),
421                offset as off64_t,
422            ))
423            .map(|n| n as usize)
424        }
425    }
426
427    #[cfg(any(
428        target_os = "aix",
429        target_os = "dragonfly", // DragonFly 1.5
430        target_os = "emscripten",
431        target_os = "freebsd",
432        target_os = "fuchsia",
433        target_os = "hurd",
434        target_os = "illumos",
435        target_os = "linux",
436        target_os = "netbsd",
437        target_os = "openbsd", // OpenBSD 2.7
438        all(target_os = "macos", target_arch = "aarch64"),
439    ))]
440    pub fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
441        let ret = cvt(unsafe {
442            libc::pwritev(
443                self.as_raw_fd(),
444                bufs.as_ptr() as *const libc::iovec,
445                cmp::min(bufs.len(), max_iov()) as libc::c_int,
446                offset as _,
447            )
448        })?;
449        Ok(ret as usize)
450    }
451
452    #[cfg(not(any(
453        target_os = "aix",
454        target_os = "android",
455        target_os = "dragonfly",
456        target_os = "emscripten",
457        target_os = "freebsd",
458        target_os = "fuchsia",
459        target_os = "hurd",
460        target_os = "illumos",
461        target_os = "linux",
462        target_os = "netbsd",
463        target_os = "openbsd",
464        target_vendor = "apple",
465    )))]
466    pub fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
467        io::default_write_vectored(|b| self.write_at(b, offset), bufs)
468    }
469
470    // We support some old Android versions that do not have `pwritev` in libc,
471    // so we use weak linkage and fallback to a direct syscall if not available.
472    //
473    // On 32-bit targets, we don't want to deal with weird ABI issues around
474    // passing 64-bits parameters to syscalls, so we fallback to the default
475    // implementation if `pwritev` is not available.
476    #[cfg(all(target_os = "android", target_pointer_width = "64"))]
477    pub fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
478        syscall!(
479            fn pwritev(
480                fd: libc::c_int,
481                iovec: *const libc::iovec,
482                n_iovec: libc::c_int,
483                offset: off64_t,
484            ) -> isize;
485        );
486
487        let ret = cvt(unsafe {
488            pwritev(
489                self.as_raw_fd(),
490                bufs.as_ptr() as *const libc::iovec,
491                cmp::min(bufs.len(), max_iov()) as libc::c_int,
492                offset as _,
493            )
494        })?;
495        Ok(ret as usize)
496    }
497
498    #[cfg(all(target_os = "android", target_pointer_width = "32"))]
499    pub fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
500        weak!(
501            fn pwritev64(
502                fd: libc::c_int,
503                iovec: *const libc::iovec,
504                n_iovec: libc::c_int,
505                offset: off64_t,
506            ) -> isize;
507        );
508
509        match pwritev64.get() {
510            Some(pwritev) => {
511                let ret = cvt(unsafe {
512                    pwritev(
513                        self.as_raw_fd(),
514                        bufs.as_ptr() as *const libc::iovec,
515                        cmp::min(bufs.len(), max_iov()) as libc::c_int,
516                        offset as _,
517                    )
518                })?;
519                Ok(ret as usize)
520            }
521            None => io::default_write_vectored(|b| self.write_at(b, offset), bufs),
522        }
523    }
524
525    // We support old MacOS, iOS, watchOS, tvOS and visionOS. `pwritev` was added in the following
526    // Apple OS versions:
527    // iOS 14.0
528    // tvOS 14.0
529    // macOS 11.0
530    // watchOS 7.0
531    //
532    // Since macOS 11.0 is also the first version with AArch64 support, we can
533    // `pwritev` unconditionally there. But on all other targets we must use
534    // "weak" linking.
535    #[cfg(all(target_vendor = "apple", not(all(target_os = "macos", target_arch = "aarch64")),))]
536    pub fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
537        weak!(
538            fn pwritev(
539                fd: libc::c_int,
540                iovec: *const libc::iovec,
541                n_iovec: libc::c_int,
542                offset: off64_t,
543            ) -> isize;
544        );
545
546        match pwritev.get() {
547            Some(pwritev) => {
548                let ret = cvt(unsafe {
549                    pwritev(
550                        self.as_raw_fd(),
551                        bufs.as_ptr() as *const libc::iovec,
552                        cmp::min(bufs.len(), max_iov()) as libc::c_int,
553                        offset as _,
554                    )
555                })?;
556                Ok(ret as usize)
557            }
558            None => io::default_write_vectored(|b| self.write_at(b, offset), bufs),
559        }
560    }
561
562    #[cfg(not(any(
563        target_env = "newlib",
564        target_os = "solaris",
565        target_os = "illumos",
566        target_os = "emscripten",
567        target_os = "fuchsia",
568        target_os = "l4re",
569        target_os = "linux",
570        target_os = "cygwin",
571        target_os = "haiku",
572        target_os = "redox",
573        target_os = "vxworks",
574        target_os = "nto",
575        target_os = "qnx",
576        target_os = "wasi",
577    )))]
578    pub fn set_cloexec(&self) -> io::Result<()> {
579        unsafe {
580            cvt(libc::ioctl(self.as_raw_fd(), libc::FIOCLEX))?;
581            Ok(())
582        }
583    }
584    #[cfg(any(
585        all(
586            target_env = "newlib",
587            not(any(target_os = "espidf", target_os = "horizon", target_os = "vita"))
588        ),
589        target_os = "solaris",
590        target_os = "illumos",
591        target_os = "emscripten",
592        target_os = "fuchsia",
593        target_os = "l4re",
594        target_os = "linux",
595        target_os = "cygwin",
596        target_os = "haiku",
597        target_os = "redox",
598        target_os = "vxworks",
599        target_os = "nto",
600        target_os = "qnx",
601        target_os = "wasi",
602    ))]
603    pub fn set_cloexec(&self) -> io::Result<()> {
604        unsafe {
605            let previous = cvt(libc::fcntl(self.as_raw_fd(), libc::F_GETFD))?;
606            let new = previous | libc::FD_CLOEXEC;
607            if new != previous {
608                cvt(libc::fcntl(self.as_raw_fd(), libc::F_SETFD, new))?;
609            }
610            Ok(())
611        }
612    }
613    #[cfg(any(target_os = "espidf", target_os = "horizon", target_os = "vita"))]
614    pub fn set_cloexec(&self) -> io::Result<()> {
615        // FD_CLOEXEC is not supported in ESP-IDF, Horizon OS and Vita but there's no need to,
616        // because none of them supports spawning processes.
617        Ok(())
618    }
619
620    #[cfg(target_os = "linux")]
621    pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
622        unsafe {
623            let v = nonblocking as libc::c_int;
624            cvt(libc::ioctl(self.as_raw_fd(), libc::FIONBIO, &v))?;
625            Ok(())
626        }
627    }
628
629    #[cfg(not(target_os = "linux"))]
630    pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
631        unsafe {
632            let previous = cvt(libc::fcntl(self.as_raw_fd(), libc::F_GETFL))?;
633            let new = if nonblocking {
634                previous | libc::O_NONBLOCK
635            } else {
636                previous & !libc::O_NONBLOCK
637            };
638            if new != previous {
639                cvt(libc::fcntl(self.as_raw_fd(), libc::F_SETFL, new))?;
640            }
641            Ok(())
642        }
643    }
644
645    #[inline]
646    pub fn duplicate(&self) -> io::Result<FileDesc> {
647        Ok(Self(self.0.try_clone()?))
648    }
649}
650
651impl<'a> Read for &'a FileDesc {
652    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
653        (**self).read(buf)
654    }
655
656    fn read_buf(&mut self, cursor: BorrowedCursor<'_, u8>) -> io::Result<()> {
657        (**self).read_buf(cursor)
658    }
659
660    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
661        (**self).read_vectored(bufs)
662    }
663
664    #[inline]
665    fn is_read_vectored(&self) -> bool {
666        (**self).is_read_vectored()
667    }
668}
669
670impl AsInner<OwnedFd> for FileDesc {
671    #[inline]
672    fn as_inner(&self) -> &OwnedFd {
673        &self.0
674    }
675}
676
677impl IntoInner<OwnedFd> for FileDesc {
678    fn into_inner(self) -> OwnedFd {
679        self.0
680    }
681}
682
683impl FromInner<OwnedFd> for FileDesc {
684    fn from_inner(owned_fd: OwnedFd) -> Self {
685        Self(owned_fd)
686    }
687}
688
689impl AsFd for FileDesc {
690    fn as_fd(&self) -> BorrowedFd<'_> {
691        self.0.as_fd()
692    }
693}
694
695impl AsRawFd for FileDesc {
696    #[inline]
697    fn as_raw_fd(&self) -> RawFd {
698        self.0.as_raw_fd()
699    }
700}
701
702impl IntoRawFd for FileDesc {
703    fn into_raw_fd(self) -> RawFd {
704        self.0.into_raw_fd()
705    }
706}
707
708impl FromRawFd for FileDesc {
709    unsafe fn from_raw_fd(raw_fd: RawFd) -> Self {
710        Self(unsafe { FromRawFd::from_raw_fd(raw_fd) })
711    }
712}