//! `pipe` and related APIs.

#![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/9799919799/functions/write.html

#[cfg(not(any(

    solarish,

    windows,

    target_os = "espidf",

    target_os = "haiku",

    target_os = "horizon",

    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.

///

/// See [`pipe_with`] to pass additional flags.

///

/// # References

///  - [POSIX]

///  - [Linux]

///  - [Apple]

///  - [FreeBSD]

///  - [NetBSD]

///  - [OpenBSD]

///  - [DragonFly BSD]

///  - [illumos]

///  - [glibc]

///

/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Creating-a-Pipe.html

#[inline]

pub fn pipe() -> io::Result<(OwnedFd, OwnedFd)> {

    backend::pipe::syscalls::pipe()

}

Unexecuted instantiation: rustix::pipe::pipe

Unexecuted instantiation: rustix::pipe::pipe

/// `pipe2(flags)`—Creates a pipe, with flags.

///

/// `pipe_with` is the same as [`pipe`] but adds an additional flags operand.

///

/// 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 = "horizon",

    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_size(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<usize> {

    backend::pipe::syscalls::fcntl_setpipe_size(fd.as_fd(), size)

}