vendor/rustix/src/pipe.rs - toolchain/rustc - Git at Google

 //! `pipe` and related APIs.
 //!
 //! # Safety
 //!
 //! `vmsplice` is an unsafe function.

 #![allow(unsafe_code)]

 use crate::fd::OwnedFd;
 use crate::{backend, io};
 #[cfg(not(any(
     solarish,
     windows,
     target_os = "espidf",
     target_os = "haiku",
     target_os = "redox",
     target_os = "vita",
     target_os = "wasi",
 )))]
 use backend::c;
 #[cfg(linux_kernel)]
 use backend::fd::AsFd;

 #[cfg(not(apple))]
 pub use backend::pipe::types::PipeFlags;

 #[cfg(linux_kernel)]
 pub use backend::pipe::types::{IoSliceRaw, SpliceFlags};

 /// `PIPE_BUF`—The maximum length at which writes to a pipe are atomic.
 ///
 /// # References
 ///  - [Linux]
 ///  - [POSIX]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man7/pipe.7.html
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html
 #[cfg(not(any(
     solarish,
     windows,
     target_os = "espidf",
     target_os = "haiku",
     target_os = "hurd",
     target_os = "redox",
     target_os = "vita",
     target_os = "wasi",
 )))]
 pub const PIPE_BUF: usize = c::PIPE_BUF;

 /// `pipe()`—Creates a pipe.
 ///
 /// This function creates a pipe and returns two file descriptors, for the
 /// reading and writing ends of the pipe, respectively.
 ///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
 ///  - [Apple]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
 ///  - [DragonFly BSD]
 ///  - [illumos]
 ///  - [glibc]
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pipe.html
 /// [Linux]: https://man7.org/linux/man-pages/man2/pipe.2.html
 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pipe.2.html
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe&sektion=2
 /// [NetBSD]: https://man.netbsd.org/pipe.2
 /// [OpenBSD]: https://man.openbsd.org/pipe.2
 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe&section=2
 /// [illumos]: https://illumos.org/man/2/pipe
 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Creating-a-Pipe.html
 #[inline]
 pub fn pipe() -> io::Result<(OwnedFd, OwnedFd)> {
     backend::pipe::syscalls::pipe()
 }

 /// `pipe2(flags)`—Creates a pipe, with flags.
 ///
 /// This function creates a pipe and returns two file descriptors, for the
 /// reading and writing ends of the pipe, respectively.
 ///
 /// # References
 ///  - [Linux]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
 ///  - [DragonFly BSD]
 ///  - [illumos]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/pipe2.2.html
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe2&sektion=2
 /// [NetBSD]: https://man.netbsd.org/pipe2.2
 /// [OpenBSD]: https://man.openbsd.org/pipe2.2
 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe2&section=2
 /// [illumos]: https://illumos.org/man/2/pipe2
 #[cfg(not(any(
     apple,
     target_os = "aix",
     target_os = "espidf",
     target_os = "haiku",
     target_os = "nto"
 )))]
 #[inline]
 #[doc(alias = "pipe2")]
 pub fn pipe_with(flags: PipeFlags) -> io::Result<(OwnedFd, OwnedFd)> {
     backend::pipe::syscalls::pipe_with(flags)
 }

 /// `splice(fd_in, off_in, fd_out, off_out, len, flags)`—Transfer data
 /// between a file and a pipe.
 ///
 /// This function transfers up to `len` bytes of data from the file descriptor
 /// `fd_in` to the file descriptor `fd_out`, where one of the file descriptors
 /// must refer to a pipe.
 ///
 /// `off_*` must be `None` if the corresponding fd refers to a pipe.
 /// Otherwise its value points to the starting offset to the file, from which
 /// the data is read/written. On success, the number of bytes read/written is
 /// added to the offset.
 ///
 /// Passing `None` causes the read/write to start from the file offset, and the
 /// file offset is adjusted appropriately.
 ///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/splice.2.html
 #[cfg(linux_kernel)]
 #[inline]
 pub fn splice<FdIn: AsFd, FdOut: AsFd>(
     fd_in: FdIn,
     off_in: Option<&mut u64>,
     fd_out: FdOut,
     off_out: Option<&mut u64>,
     len: usize,
     flags: SpliceFlags,
 ) -> io::Result<usize> {
     backend::pipe::syscalls::splice(fd_in.as_fd(), off_in, fd_out.as_fd(), off_out, len, flags)
 }

 /// `vmsplice(fd, bufs, flags)`—Transfer data between memory and a pipe.
 ///
 /// If `fd` is the write end of the pipe,
 /// the function maps the memory pointer at by `bufs` to the pipe.
 ///
 /// If `fd` is the read end of the pipe,
 /// the function writes data from the pipe to said memory.
 ///
 /// # Safety
 ///
 /// If the memory must not be mutated (such as when `bufs` were originally
 /// immutable slices), it is up to the caller to ensure that the write end of
 /// the pipe is placed in `fd`.
 ///
 /// Additionally if `SpliceFlags::GIFT` is set, the caller must also ensure
 /// that the contents of `bufs` in never modified following the call, and that
 /// all of the pointers in `bufs` are page aligned, and the lengths are
 /// multiples of a page size in bytes.
 ///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/vmsplice.2.html
 #[cfg(linux_kernel)]
 #[inline]
 pub unsafe fn vmsplice<PipeFd: AsFd>(
     fd: PipeFd,
     bufs: &[IoSliceRaw<'_>],
     flags: SpliceFlags,
 ) -> io::Result<usize> {
     backend::pipe::syscalls::vmsplice(fd.as_fd(), bufs, flags)
 }

 /// `tee(fd_in, fd_out, len, flags)`—Copy data between pipes without
 /// consuming it.
 ///
 /// This reads up to `len` bytes from `in_fd` without consuming them, and
 /// writes them to `out_fd`.
 ///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/tee.2.html
 #[cfg(linux_kernel)]
 #[inline]
 pub fn tee<FdIn: AsFd, FdOut: AsFd>(
     fd_in: FdIn,
     fd_out: FdOut,
     len: usize,
     flags: SpliceFlags,
 ) -> io::Result<usize> {
     backend::pipe::syscalls::tee(fd_in.as_fd(), fd_out.as_fd(), len, flags)
 }

 /// `fnctl(fd, F_GETPIPE_SZ)`—Return the buffer capacity of a pipe.
 ///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
 #[cfg(linux_kernel)]
 #[inline]
 pub fn fcntl_getpipe_size<Fd: AsFd>(fd: Fd) -> io::Result<usize> {
     backend::pipe::syscalls::fcntl_getpipe_sz(fd.as_fd())
 }

 /// `fnctl(fd, F_SETPIPE_SZ)`—Set the buffer capacity of a pipe.
 ///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
 #[cfg(linux_kernel)]
 #[inline]
 pub fn fcntl_setpipe_size<Fd: AsFd>(fd: Fd, size: usize) -> io::Result<()> {
     backend::pipe::syscalls::fcntl_setpipe_sz(fd.as_fd(), size)
 }
	//! `pipe` and related APIs.
	//!
	//! # Safety
	//!
	//! `vmsplice` is an unsafe function.

	#![allow(unsafe_code)]

	use crate::fd::OwnedFd;
	use crate::{backend, io};
	#[cfg(not(any(
	solarish,
	windows,
	target_os = "espidf",
	target_os = "haiku",
	target_os = "redox",
	target_os = "vita",
	target_os = "wasi",
	)))]
	use backend::c;
	#[cfg(linux_kernel)]
	use backend::fd::AsFd;

	#[cfg(not(apple))]
	pub use backend::pipe::types::PipeFlags;

	#[cfg(linux_kernel)]
	pub use backend::pipe::types::{IoSliceRaw, SpliceFlags};

	/// `PIPE_BUF`—The maximum length at which writes to a pipe are atomic.
	///
	/// # References
	/// - [Linux]
	/// - [POSIX]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man7/pipe.7.html
	/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html
	#[cfg(not(any(
	solarish,
	windows,
	target_os = "espidf",
	target_os = "haiku",
	target_os = "hurd",
	target_os = "redox",
	target_os = "vita",
	target_os = "wasi",
	)))]
	pub const PIPE_BUF: usize = c::PIPE_BUF;

	/// `pipe()`—Creates a pipe.
	///
	/// This function creates a pipe and returns two file descriptors, for the
	/// reading and writing ends of the pipe, respectively.
	///
	/// # References
	/// - [POSIX]
	/// - [Linux]
	/// - [Apple]
	/// - [FreeBSD]
	/// - [NetBSD]
	/// - [OpenBSD]
	/// - [DragonFly BSD]
	/// - [illumos]
	/// - [glibc]
	///
	/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pipe.html
	/// [Linux]: https://man7.org/linux/man-pages/man2/pipe.2.html
	/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pipe.2.html
	/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe&sektion=2
	/// [NetBSD]: https://man.netbsd.org/pipe.2
	/// [OpenBSD]: https://man.openbsd.org/pipe.2
	/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe&section=2
	/// [illumos]: https://illumos.org/man/2/pipe
	/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Creating-a-Pipe.html
	#[inline]
	pub fn pipe() -> io::Result<(OwnedFd, OwnedFd)> {
	backend::pipe::syscalls::pipe()
	}

	/// `pipe2(flags)`—Creates a pipe, with flags.
	///
	/// This function creates a pipe and returns two file descriptors, for the
	/// reading and writing ends of the pipe, respectively.
	///
	/// # References
	/// - [Linux]
	/// - [FreeBSD]
	/// - [NetBSD]
	/// - [OpenBSD]
	/// - [DragonFly BSD]
	/// - [illumos]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/pipe2.2.html
	/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe2&sektion=2
	/// [NetBSD]: https://man.netbsd.org/pipe2.2
	/// [OpenBSD]: https://man.openbsd.org/pipe2.2
	/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe2&section=2
	/// [illumos]: https://illumos.org/man/2/pipe2
	#[cfg(not(any(
	apple,
	target_os = "aix",
	target_os = "espidf",
	target_os = "haiku",
	target_os = "nto"
	)))]
	#[inline]
	#[doc(alias = "pipe2")]
	pub fn pipe_with(flags: PipeFlags) -> io::Result<(OwnedFd, OwnedFd)> {
	backend::pipe::syscalls::pipe_with(flags)
	}

	/// `splice(fd_in, off_in, fd_out, off_out, len, flags)`—Transfer data
	/// between a file and a pipe.
	///
	/// This function transfers up to `len` bytes of data from the file descriptor
	/// `fd_in` to the file descriptor `fd_out`, where one of the file descriptors
	/// must refer to a pipe.
	///
	/// `off_*` must be `None` if the corresponding fd refers to a pipe.
	/// Otherwise its value points to the starting offset to the file, from which
	/// the data is read/written. On success, the number of bytes read/written is
	/// added to the offset.
	///
	/// Passing `None` causes the read/write to start from the file offset, and the
	/// file offset is adjusted appropriately.
	///
	/// # References
	/// - [Linux]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/splice.2.html
	#[cfg(linux_kernel)]
	#[inline]
	pub fn splice<FdIn: AsFd, FdOut: AsFd>(
	fd_in: FdIn,
	off_in: Option<&mut u64>,
	fd_out: FdOut,
	off_out: Option<&mut u64>,
	len: usize,
	flags: SpliceFlags,
	) -> io::Result<usize> {
	backend::pipe::syscalls::splice(fd_in.as_fd(), off_in, fd_out.as_fd(), off_out, len, flags)
	}

	/// `vmsplice(fd, bufs, flags)`—Transfer data between memory and a pipe.
	///
	/// If `fd` is the write end of the pipe,
	/// the function maps the memory pointer at by `bufs` to the pipe.
	///
	/// If `fd` is the read end of the pipe,
	/// the function writes data from the pipe to said memory.
	///
	/// # Safety
	///
	/// If the memory must not be mutated (such as when `bufs` were originally
	/// immutable slices), it is up to the caller to ensure that the write end of
	/// the pipe is placed in `fd`.
	///
	/// Additionally if `SpliceFlags::GIFT` is set, the caller must also ensure
	/// that the contents of `bufs` in never modified following the call, and that
	/// all of the pointers in `bufs` are page aligned, and the lengths are
	/// multiples of a page size in bytes.
	///
	/// # References
	/// - [Linux]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/vmsplice.2.html
	#[cfg(linux_kernel)]
	#[inline]
	pub unsafe fn vmsplice<PipeFd: AsFd>(
	fd: PipeFd,
	bufs: &[IoSliceRaw<'_>],
	flags: SpliceFlags,
	) -> io::Result<usize> {
	backend::pipe::syscalls::vmsplice(fd.as_fd(), bufs, flags)
	}

	/// `tee(fd_in, fd_out, len, flags)`—Copy data between pipes without
	/// consuming it.
	///
	/// This reads up to `len` bytes from `in_fd` without consuming them, and
	/// writes them to `out_fd`.
	///
	/// # References
	/// - [Linux]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/tee.2.html
	#[cfg(linux_kernel)]
	#[inline]
	pub fn tee<FdIn: AsFd, FdOut: AsFd>(
	fd_in: FdIn,
	fd_out: FdOut,
	len: usize,
	flags: SpliceFlags,
	) -> io::Result<usize> {
	backend::pipe::syscalls::tee(fd_in.as_fd(), fd_out.as_fd(), len, flags)
	}

	/// `fnctl(fd, F_GETPIPE_SZ)`—Return the buffer capacity of a pipe.
	///
	/// # References
	/// - [Linux]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
	#[cfg(linux_kernel)]
	#[inline]
	pub fn fcntl_getpipe_size<Fd: AsFd>(fd: Fd) -> io::Result<usize> {
	backend::pipe::syscalls::fcntl_getpipe_sz(fd.as_fd())
	}

	/// `fnctl(fd, F_SETPIPE_SZ)`—Set the buffer capacity of a pipe.
	///
	/// # References
	/// - [Linux]
	///
	/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
	#[cfg(linux_kernel)]
	#[inline]
	pub fn fcntl_setpipe_size<Fd: AsFd>(fd: Fd, size: usize) -> io::Result<()> {
	backend::pipe::syscalls::fcntl_setpipe_sz(fd.as_fd(), size)
	}