rustix/
pipe.rs

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

rustix/
pipe.rs
