rustix/
pipe.rs

1//! `pipe` and related APIs.
2
3#![allow(unsafe_code)]
4
5use crate::fd::OwnedFd;
6use crate::{backend, io};
7#[cfg(not(any(
8    solarish,
9    windows,
10    target_os = "espidf",
11    target_os = "haiku",
12    target_os = "horizon",
13    target_os = "redox",
14    target_os = "vita",
15    target_os = "wasi",
16)))]
17use backend::c;
18#[cfg(linux_kernel)]
19use backend::fd::AsFd;
20
21#[cfg(not(apple))]
22pub use backend::pipe::types::PipeFlags;
23
24#[cfg(linux_kernel)]
25pub use backend::pipe::types::{IoSliceRaw, SpliceFlags};
26
27/// `PIPE_BUF`—The maximum length at which writes to a pipe are atomic.
28///
29/// # References
30///  - [Linux]
31///  - [POSIX]
32///
33/// [Linux]: https://man7.org/linux/man-pages/man7/pipe.7.html
34/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/write.html
35#[cfg(not(any(
36    solarish,
37    windows,
38    target_os = "espidf",
39    target_os = "haiku",
40    target_os = "horizon",
41    target_os = "hurd",
42    target_os = "redox",
43    target_os = "vita",
44    target_os = "wasi",
45)))]
46pub const PIPE_BUF: usize = c::PIPE_BUF;
47
48/// `pipe()`—Creates a pipe.
49///
50/// This function creates a pipe and returns two file descriptors, for the
51/// reading and writing ends of the pipe, respectively.
52///
53/// See [`pipe_with`] to pass additional flags.
54///
55/// # References
56///  - [POSIX]
57///  - [Linux]
58///  - [Apple]
59///  - [FreeBSD]
60///  - [NetBSD]
61///  - [OpenBSD]
62///  - [DragonFly BSD]
63///  - [illumos]
64///  - [glibc]
65///
66/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/pipe.html
67/// [Linux]: https://man7.org/linux/man-pages/man2/pipe.2.html
68/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/pipe.2.html
69/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe&sektion=2
70/// [NetBSD]: https://man.netbsd.org/pipe.2
71/// [OpenBSD]: https://man.openbsd.org/pipe.2
72/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe&section=2
73/// [illumos]: https://illumos.org/man/2/pipe
74/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Creating-a-Pipe.html
75#[inline]
76pub fn pipe() -> io::Result<(OwnedFd, OwnedFd)> {
77    backend::pipe::syscalls::pipe()
78}
79
80/// `pipe2(flags)`—Creates a pipe, with flags.
81///
82/// `pipe_with` is the same as [`pipe`] but adds an additional flags operand.
83///
84/// This function creates a pipe and returns two file descriptors, for the
85/// reading and writing ends of the pipe, respectively.
86///
87/// # References
88///  - [Linux]
89///  - [FreeBSD]
90///  - [NetBSD]
91///  - [OpenBSD]
92///  - [DragonFly BSD]
93///  - [illumos]
94///
95/// [Linux]: https://man7.org/linux/man-pages/man2/pipe2.2.html
96/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=pipe2&sektion=2
97/// [NetBSD]: https://man.netbsd.org/pipe2.2
98/// [OpenBSD]: https://man.openbsd.org/pipe2.2
99/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=pipe2&section=2
100/// [illumos]: https://illumos.org/man/2/pipe2
101#[cfg(not(any(
102    apple,
103    target_os = "aix",
104    target_os = "espidf",
105    target_os = "haiku",
106    target_os = "horizon",
107    target_os = "nto"
108)))]
109#[inline]
110#[doc(alias = "pipe2")]
111pub fn pipe_with(flags: PipeFlags) -> io::Result<(OwnedFd, OwnedFd)> {
112    backend::pipe::syscalls::pipe_with(flags)
113}
114
115/// `splice(fd_in, off_in, fd_out, off_out, len, flags)`—Transfer data
116/// between a file and a pipe.
117///
118/// This function transfers up to `len` bytes of data from the file descriptor
119/// `fd_in` to the file descriptor `fd_out`, where one of the file descriptors
120/// must refer to a pipe.
121///
122/// `off_*` must be `None` if the corresponding fd refers to a pipe. Otherwise
123/// its value points to the starting offset to the file, from which the data is
124/// read/written. On success, the number of bytes read/written is added to the
125/// offset.
126///
127/// Passing `None` causes the read/write to start from the file offset, and the
128/// file offset is adjusted appropriately.
129///
130/// # References
131///  - [Linux]
132///
133/// [Linux]: https://man7.org/linux/man-pages/man2/splice.2.html
134#[cfg(linux_kernel)]
135#[inline]
136pub fn splice<FdIn: AsFd, FdOut: AsFd>(
137    fd_in: FdIn,
138    off_in: Option<&mut u64>,
139    fd_out: FdOut,
140    off_out: Option<&mut u64>,
141    len: usize,
142    flags: SpliceFlags,
143) -> io::Result<usize> {
144    backend::pipe::syscalls::splice(fd_in.as_fd(), off_in, fd_out.as_fd(), off_out, len, flags)
145}
146
147/// `vmsplice(fd, bufs, flags)`—Transfer data between memory and a pipe.
148///
149/// If `fd` is the write end of the pipe, the function maps the memory pointer
150/// at by `bufs` to the pipe.
151///
152/// If `fd` is the read end of the pipe, the function writes data from the pipe
153/// to said memory.
154///
155/// # Safety
156///
157/// If the memory must not be mutated (such as when `bufs` were originally
158/// immutable slices), it is up to the caller to ensure that the write end of
159/// the pipe is placed in `fd`.
160///
161/// Additionally if `SpliceFlags::GIFT` is set, the caller must also ensure
162/// that the contents of `bufs` in never modified following the call, and that
163/// all of the pointers in `bufs` are page aligned, and the lengths are
164/// multiples of a page size in bytes.
165///
166/// # References
167///  - [Linux]
168///
169/// [Linux]: https://man7.org/linux/man-pages/man2/vmsplice.2.html
170#[cfg(linux_kernel)]
171#[inline]
172pub unsafe fn vmsplice<PipeFd: AsFd>(
173    fd: PipeFd,
174    bufs: &[IoSliceRaw<'_>],
175    flags: SpliceFlags,
176) -> io::Result<usize> {
177    backend::pipe::syscalls::vmsplice(fd.as_fd(), bufs, flags)
178}
179
180/// `tee(fd_in, fd_out, len, flags)`—Copy data between pipes without
181/// consuming it.
182///
183/// This reads up to `len` bytes from `in_fd` without consuming them, and
184/// writes them to `out_fd`.
185///
186/// # References
187///  - [Linux]
188///
189/// [Linux]: https://man7.org/linux/man-pages/man2/tee.2.html
190#[cfg(linux_kernel)]
191#[inline]
192pub fn tee<FdIn: AsFd, FdOut: AsFd>(
193    fd_in: FdIn,
194    fd_out: FdOut,
195    len: usize,
196    flags: SpliceFlags,
197) -> io::Result<usize> {
198    backend::pipe::syscalls::tee(fd_in.as_fd(), fd_out.as_fd(), len, flags)
199}
200
201/// `fnctl(fd, F_GETPIPE_SZ)`—Return the buffer capacity of a pipe.
202///
203/// # References
204///  - [Linux]
205///
206/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
207#[cfg(linux_kernel)]
208#[inline]
209pub fn fcntl_getpipe_size<Fd: AsFd>(fd: Fd) -> io::Result<usize> {
210    backend::pipe::syscalls::fcntl_getpipe_size(fd.as_fd())
211}
212
213/// `fnctl(fd, F_SETPIPE_SZ)`—Set the buffer capacity of a pipe.
214///
215/// # References
216///  - [Linux]
217///
218/// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
219#[cfg(linux_kernel)]
220#[inline]
221pub fn fcntl_setpipe_size<Fd: AsFd>(fd: Fd, size: usize) -> io::Result<usize> {
222    backend::pipe::syscalls::fcntl_setpipe_size(fd.as_fd(), size)
223}
rustix/pipe.rs

rustix/
pipe.rs
