Source code
Revision control
Copy as Markdown
Other Tools
//! `read` and `write`, optionally positioned, optionally vectored
#![allow(unsafe_code)]
use crate::buffer::split_init;
use crate::{backend, io};
use backend::fd::AsFd;
use core::mem::MaybeUninit;
// Declare `IoSlice` and `IoSliceMut`.
#[cfg(not(windows))]
pub use crate::maybe_polyfill::io::{IoSlice, IoSliceMut};
#[cfg(linux_kernel)]
pub use backend::io::types::ReadWriteFlags;
/// `read(fd, buf)`—Reads from a stream.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
/// - [glibc]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/read.2.html
/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/I_002fO-Primitives.html#index-reading-from-a-file-descriptor
#[inline]
pub fn read<Fd: AsFd>(fd: Fd, buf: &mut [u8]) -> io::Result<usize> {
unsafe { backend::io::syscalls::read(fd.as_fd(), buf.as_mut_ptr(), buf.len()) }
}
/// `read(fd, buf)`—Reads from a stream.
///
/// This is equivalent to [`read`], except that it can read into uninitialized
/// memory. It returns the slice that was initialized by this function and the
/// slice that remains uninitialized.
#[inline]
pub fn read_uninit<Fd: AsFd>(
fd: Fd,
buf: &mut [MaybeUninit<u8>],
) -> io::Result<(&mut [u8], &mut [MaybeUninit<u8>])> {
// Get number of initialized bytes.
let length =
unsafe { backend::io::syscalls::read(fd.as_fd(), buf.as_mut_ptr() as *mut u8, buf.len()) };
// Split into the initialized and uninitialized portions.
Ok(unsafe { split_init(buf, length?) })
}
/// `write(fd, buf)`—Writes to a stream.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
/// - [glibc]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/write.2.html
/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/I_002fO-Primitives.html#index-writing-to-a-file-descriptor
#[inline]
pub fn write<Fd: AsFd>(fd: Fd, buf: &[u8]) -> io::Result<usize> {
backend::io::syscalls::write(fd.as_fd(), buf)
}
/// `pread(fd, buf, offset)`—Reads from a file at a given position.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pread.2.html
#[inline]
pub fn pread<Fd: AsFd>(fd: Fd, buf: &mut [u8], offset: u64) -> io::Result<usize> {
unsafe { backend::io::syscalls::pread(fd.as_fd(), buf.as_mut_ptr(), buf.len(), offset) }
}
/// `pread(fd, buf, offset)`—Reads from a file at a given position.
///
/// This is equivalent to [`pread`], except that it can read into uninitialized
/// memory. It returns the slice that was initialized by this function and the
/// slice that remains uninitialized.
#[inline]
pub fn pread_uninit<Fd: AsFd>(
fd: Fd,
buf: &mut [MaybeUninit<u8>],
offset: u64,
) -> io::Result<(&mut [u8], &mut [MaybeUninit<u8>])> {
let length = unsafe {
backend::io::syscalls::pread(fd.as_fd(), buf.as_mut_ptr() as *mut u8, buf.len(), offset)
};
Ok(unsafe { split_init(buf, length?) })
}
/// `pwrite(fd, bufs)`—Writes to a file at a given position.
///
/// Contrary to POSIX, on many popular platforms including Linux and FreeBSD,
/// if the file is opened in append mode, this ignores the offset appends the
/// data to the end of the file.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pwrite.2.html
#[inline]
pub fn pwrite<Fd: AsFd>(fd: Fd, buf: &[u8], offset: u64) -> io::Result<usize> {
backend::io::syscalls::pwrite(fd.as_fd(), buf, offset)
}
/// `readv(fd, bufs)`—Reads from a stream into multiple buffers.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/readv.2.html
#[cfg(not(any(target_os = "espidf", target_os = "horizon")))]
#[inline]
pub fn readv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
backend::io::syscalls::readv(fd.as_fd(), bufs)
}
/// `writev(fd, bufs)`—Writes to a stream from multiple buffers.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/writev.2.html
#[cfg(not(any(target_os = "espidf", target_os = "horizon")))]
#[inline]
pub fn writev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
backend::io::syscalls::writev(fd.as_fd(), bufs)
}
/// `preadv(fd, bufs, offset)`—Reads from a file at a given position into
/// multiple buffers.
///
/// # References
/// - [Linux]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
#[cfg(not(any(
target_os = "espidf",
target_os = "haiku",
target_os = "horizon",
target_os = "nto",
target_os = "redox",
target_os = "solaris",
target_os = "vita"
)))]
#[inline]
pub fn preadv<Fd: AsFd>(fd: Fd, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
backend::io::syscalls::preadv(fd.as_fd(), bufs, offset)
}
/// `pwritev(fd, bufs, offset)`—Writes to a file at a given position from
/// multiple buffers.
///
/// Contrary to POSIX, on many popular platforms including Linux and FreeBSD,
/// if the file is opened in append mode, this ignores the offset appends the
/// data to the end of the file.
///
/// # References
/// - [Linux]
/// - [FreeBSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [DragonFly BSD]
/// - [illumos]
///
#[cfg(not(any(
target_os = "espidf",
target_os = "haiku",
target_os = "horizon",
target_os = "nto",
target_os = "redox",
target_os = "solaris",
target_os = "vita"
)))]
#[inline]
pub fn pwritev<Fd: AsFd>(fd: Fd, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
backend::io::syscalls::pwritev(fd.as_fd(), bufs, offset)
}
/// `preadv2(fd, bufs, offset, flags)`—Reads data, with several options.
///
/// An `offset` of `u64::MAX` means to use and update the current file offset.
///
/// # References
/// - [Linux]
///
#[cfg(linux_kernel)]
#[inline]
pub fn preadv2<Fd: AsFd>(
fd: Fd,
bufs: &mut [IoSliceMut<'_>],
offset: u64,
flags: ReadWriteFlags,
) -> io::Result<usize> {
backend::io::syscalls::preadv2(fd.as_fd(), bufs, offset, flags)
}
/// `pwritev2(fd, bufs, offset, flags)`—Writes data, with several options.
///
/// An `offset` of `u64::MAX` means to use and update the current file offset.
///
/// # References
/// - [Linux]
///
#[cfg(linux_kernel)]
#[inline]
pub fn pwritev2<Fd: AsFd>(
fd: Fd,
bufs: &[IoSlice<'_>],
offset: u64,
flags: ReadWriteFlags,
) -> io::Result<usize> {
backend::io::syscalls::pwritev2(fd.as_fd(), bufs, offset, flags)
}