1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
//! Pseudoterminal operations.
//!
//! For the `openpty` and `login_tty` functions, see the
//! [rustix-openpty crate].
//!
//! [rustix-openpty crate]: https://crates.io/crates/rustix-openpty
use crate::backend::c;
use crate::fd::{AsFd, OwnedFd};
use crate::fs::OFlags;
use crate::{backend, io};
#[cfg(any(apple, linux_like, target_os = "freebsd", target_os = "fuchsia"))]
use {crate::ffi::CString, alloc::vec::Vec};
bitflags::bitflags! {
/// `O_*` flags for use with [`openpt`] and [`ioctl_tiocgptpeer`].
///
/// [`ioctl_tiocgtpeer`]: https://docs.rs/rustix/*/x86_64-unknown-linux-gnu/rustix/pty/fn.ioctl_tiocgtpeer.html
pub struct OpenptFlags: u32 {
/// `O_RDWR`
const RDWR = c::O_RDWR as c::c_uint;
/// `O_NOCTTY`
#[cfg(not(target_os = "redox"))]
const NOCTTY = c::O_NOCTTY as c::c_uint;
/// `O_CLOEXEC`
///
/// The standard `posix_openpt` function doesn't support `CLOEXEC`, but
/// rustix supports it on Linux, and FreeBSD and NetBSD support it.
#[cfg(any(linux_kernel, target_os = "freebsd", target_os = "netbsd"))]
const CLOEXEC = c::O_CLOEXEC as c::c_uint;
}
}
impl From<OpenptFlags> for OFlags {
#[inline]
fn from(flags: OpenptFlags) -> Self {
// SAFETY: `OpenptFlags` is a subset of `OFlags`.
#[allow(unsafe_code)]
unsafe {
Self::from_bits_unchecked(flags.bits() as _)
}
}
}
/// `posix_openpt(flags)`—Open a pseudoterminal device.
///
/// On Linux, an additional `CLOEXEC` flag value may be passed to request the
/// close-on-exec flag be set.
///
/// On Linux, if the system has no free pseudoterminals available, the
/// underlying system call fails with [`io::Errno::NOSPC`], however this rustix
/// function translates that to [`io::Errno::AGAIN`], so that the linux_raw and
/// libc backends have the same behavior.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [Apple]
/// - [FreeBSD]
/// - [DragonFly BSD]
/// - [NetBSD]
/// - [OpenBSD]
/// - [illumos]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_openpt.html
/// [Linux]: https://man7.org/linux/man-pages/man3/posix_openpt.3.html
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/posix_openpt.3.html
/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=posix_openpt&sektion=2
/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=posix_openpt§ion=3
/// [NetBSD]: https://man.netbsd.org/posix_openpt.3
/// [OpenBSD]: https://man.openbsd.org/posix_openpt
/// [illumos]: https://illumos.org/man/3C/posix_openpt
#[inline]
#[doc(alias = "posix_openpt")]
pub fn openpt(flags: OpenptFlags) -> io::Result<OwnedFd> {
// On Linux, open the device ourselves so that we can support `CLOEXEC`.
#[cfg(linux_kernel)]
{
use crate::fs::{cwd, openat, Mode};
match openat(cwd(), cstr!("/dev/ptmx"), flags.into(), Mode::empty()) {
// Match libc `openat` behavior with `ENOSPC`.
Err(io::Errno::NOSPC) => Err(io::Errno::AGAIN),
otherwise => otherwise,
}
}
// On all other platforms, use `openpt`.
#[cfg(not(linux_kernel))]
{
backend::pty::syscalls::openpt(flags)
}
}
/// `ptsname(fd)`—Return the name of a pseudoterminal.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [glibc]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/ptsname.html
/// [Linux]: https://man7.org/linux/man-pages/man3/ptsname.3.html
/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Allocation.html#index-ptsname
#[inline]
#[doc(alias = "ptsname_r")]
#[cfg(any(apple, linux_like, target_os = "freebsd", target_os = "fuchsia"))]
pub fn ptsname<Fd: AsFd, B: Into<Vec<u8>>>(fd: Fd, reuse: B) -> io::Result<CString> {
backend::pty::syscalls::ptsname(fd.as_fd(), reuse.into())
}
/// `unlockpt(fd)`—Unlock a pseudoterminal.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [glibc]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/unlockpt.html
/// [Linux]: https://man7.org/linux/man-pages/man3/unlockpt.3.html
/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Allocation.html#index-unlockpt
#[inline]
pub fn unlockpt<Fd: AsFd>(fd: Fd) -> io::Result<()> {
backend::pty::syscalls::unlockpt(fd.as_fd())
}
/// `grantpt(fd)`—Grant access to the user side of a pseudoterminal.
///
/// On Linux, calling this function has no effect, as the kernel is expected to
/// grant the appropriate access. On all other platorms, this function has
/// unspecified behavior if the calling process has a `SIGCHLD` signal handler
/// installed.
///
/// # References
/// - [POSIX]
/// - [Linux]
/// - [glibc]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/grantpt.html
/// [Linux]: https://man7.org/linux/man-pages/man3/grantpt.3.html
/// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Allocation.html#index-grantpt
#[inline]
pub fn grantpt<Fd: AsFd>(fd: Fd) -> io::Result<()> {
#[cfg(not(linux_kernel))]
{
backend::pty::syscalls::grantpt(fd.as_fd())
}
// On Linux, we assume the kernel has already granted the needed
// permissions to the user side of the pseudoterminal.
#[cfg(linux_kernel)]
{
let _ = fd;
Ok(())
}
}
/// `ioctl(fd, TIOCGPTPEER)`—Open the user side of a pseduoterminal.
///
/// This function is currently only implemented on Linux.
///
/// # References
/// - [Linux]
///
/// [Linux]: https://man7.org/linux/man-pages/man2/ioctl_tty.2.html
#[cfg(target_os = "linux")]
#[inline]
pub fn ioctl_tiocgptpeer<Fd: AsFd>(fd: Fd, flags: OpenptFlags) -> io::Result<OwnedFd> {
backend::pty::syscalls::ioctl_tiocgptpeer(fd.as_fd(), flags)
}