| //! Unsafe `ioctl` API. |
| //! |
| //! Unix systems expose a number of `ioctl`'s. `ioctl`s have been adopted as a |
| //! general purpose system call for making calls into the kernel. In addition |
| //! to the wide variety of system calls that are included by default in the |
| //! kernel, many drivers expose their own `ioctl`'s for controlling their |
| //! behavior, some of which are proprietary. Therefore it is impossible to make |
| //! a safe interface for every `ioctl` call, as they all have wildly varying |
| //! semantics. |
| //! |
| //! This module provides an unsafe interface to write your own `ioctl` API. To |
| //! start, create a type that implements [`Ioctl`]. Then, pass it to [`ioctl`] |
| //! to make the `ioctl` call. |
| |
| #![allow(unsafe_code)] |
| |
| use crate::backend::c; |
| use crate::fd::{AsFd, BorrowedFd}; |
| use crate::io::Result; |
| |
| #[cfg(any(linux_kernel, bsd))] |
| use core::mem; |
| |
| pub use patterns::*; |
| |
| mod patterns; |
| |
| #[cfg(linux_kernel)] |
| mod linux; |
| |
| #[cfg(bsd)] |
| mod bsd; |
| |
| #[cfg(linux_kernel)] |
| use linux as platform; |
| |
| #[cfg(bsd)] |
| use bsd as platform; |
| |
| /// Perform an `ioctl` call. |
| /// |
| /// `ioctl` was originally intended to act as a way of modifying the behavior |
| /// of files, but has since been adopted as a general purpose system call for |
| /// making calls into the kernel. In addition to the default calls exposed by |
| /// generic file descriptors, many drivers expose their own `ioctl` calls for |
| /// controlling their behavior, some of which are proprietary. |
| /// |
| /// This crate exposes many other `ioctl` interfaces with safe and idiomatic |
| /// wrappers, like [`ioctl_fionbio`](crate::io::ioctl_fionbio) and |
| /// [`ioctl_fionread`](crate::io::ioctl_fionread). It is recommended to use |
| /// those instead of this function, as they are safer and more idiomatic. |
| /// For other cases, implement the [`Ioctl`] API and pass it to this function. |
| /// |
| /// See documentation for [`Ioctl`] for more information. |
| /// |
| /// # Safety |
| /// |
| /// While [`Ioctl`] takes much of the unsafety out of `ioctl` calls, it is |
| /// still unsafe to call this code with arbitrary device drivers, as it is up |
| /// to the device driver to implement the `ioctl` call correctly. It is on the |
| /// onus of the protocol between the user and the driver to ensure that the |
| /// `ioctl` call is safe to make. |
| /// |
| /// # References |
| /// |
| /// - [Linux] |
| /// - [WinSock2] |
| /// - [FreeBSD] |
| /// - [NetBSD] |
| /// - [OpenBSD] |
| /// - [Apple] |
| /// - [Solaris] |
| /// - [illumos] |
| /// |
| /// [Linux]: https://man7.org/linux/man-pages/man2/ioctl.2.html |
| /// [Winsock2]: https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-ioctlsocket |
| /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=ioctl&sektion=2 |
| /// [NetBSD]: https://man.netbsd.org/ioctl.2 |
| /// [OpenBSD]: https://man.openbsd.org/ioctl.2 |
| /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/ioctl.2.html |
| /// [Solaris]: https://docs.oracle.com/cd/E23824_01/html/821-1463/ioctl-2.html |
| /// [illumos]: https://illumos.org/man/2/ioctl |
| #[inline] |
| pub unsafe fn ioctl<F: AsFd, I: Ioctl>(fd: F, mut ioctl: I) -> Result<I::Output> { |
| let fd = fd.as_fd(); |
| let request = I::OPCODE.raw(); |
| let arg = ioctl.as_ptr(); |
| |
| // SAFETY: The variant of `Ioctl` asserts that this is a valid IOCTL call |
| // to make. |
| let output = if I::IS_MUTATING { |
| _ioctl(fd, request, arg)? |
| } else { |
| _ioctl_readonly(fd, request, arg)? |
| }; |
| |
| // SAFETY: The variant of `Ioctl` asserts that this is a valid pointer to |
| // the output data. |
| I::output_from_ptr(output, arg) |
| } |
| |
| unsafe fn _ioctl( |
| fd: BorrowedFd<'_>, |
| request: RawOpcode, |
| arg: *mut c::c_void, |
| ) -> Result<IoctlOutput> { |
| crate::backend::io::syscalls::ioctl(fd, request, arg) |
| } |
| |
| unsafe fn _ioctl_readonly( |
| fd: BorrowedFd<'_>, |
| request: RawOpcode, |
| arg: *mut c::c_void, |
| ) -> Result<IoctlOutput> { |
| crate::backend::io::syscalls::ioctl_readonly(fd, request, arg) |
| } |
| |
| /// A trait defining the properties of an `ioctl` command. |
| /// |
| /// Objects implementing this trait can be passed to [`ioctl`] to make an |
| /// `ioctl` call. The contents of the object represent the inputs to the |
| /// `ioctl` call. The inputs must be convertible to a pointer through the |
| /// `as_ptr` method. In most cases, this involves either casting a number to a |
| /// pointer, or creating a pointer to the actual data. The latter case is |
| /// necessary for `ioctl` calls that modify userspace data. |
| /// |
| /// # Safety |
| /// |
| /// This trait is unsafe to implement because it is impossible to guarantee |
| /// that the `ioctl` call is safe. The `ioctl` call may be proprietary, or it |
| /// may be unsafe to call in certain circumstances. |
| /// |
| /// By implementing this trait, you guarantee that: |
| /// |
| /// - The `ioctl` call expects the input provided by `as_ptr` and produces the |
| /// output as indicated by `output`. |
| /// - That `output_from_ptr` can safely take the pointer from `as_ptr` and cast |
| /// it to the correct type, *only* after the `ioctl` call. |
| /// - That `OPCODE` uniquely identifies the `ioctl` call. |
| /// - That, for whatever platforms you are targeting, the `ioctl` call is safe |
| /// to make. |
| /// - If `IS_MUTATING` is false, that no userspace data will be modified by the |
| /// `ioctl` call. |
| pub unsafe trait Ioctl { |
| /// The type of the output data. |
| /// |
| /// Given a pointer, one should be able to construct an instance of this |
| /// type. |
| type Output; |
| |
| /// The opcode used by this `ioctl` command. |
| /// |
| /// There are different types of opcode depending on the operation. See |
| /// documentation for the [`Opcode`] struct for more information. |
| const OPCODE: Opcode; |
| |
| /// Does the `ioctl` mutate any data in the userspace? |
| /// |
| /// If the `ioctl` call does not mutate any data in the userspace, then |
| /// making this `false` enables optimizations that can make the call |
| /// faster. When in doubt, set this to `true`. |
| /// |
| /// # Safety |
| /// |
| /// This should only be set to `false` if the `ioctl` call does not mutate |
| /// any data in the userspace. Undefined behavior may occur if this is set |
| /// to `false` when it should be `true`. |
| const IS_MUTATING: bool; |
| |
| /// Get a pointer to the data to be passed to the `ioctl` command. |
| /// |
| /// See trait-level documentation for more information. |
| fn as_ptr(&mut self) -> *mut c::c_void; |
| |
| /// Cast the output data to the correct type. |
| /// |
| /// # Safety |
| /// |
| /// The `extract_output` value must be the resulting value after a |
| /// successful `ioctl` call, and `out` is the direct return value of an |
| /// `ioctl` call that did not fail. In this case `extract_output` is the |
| /// pointer that was passed to the `ioctl` call. |
| unsafe fn output_from_ptr( |
| out: IoctlOutput, |
| extract_output: *mut c::c_void, |
| ) -> Result<Self::Output>; |
| } |
| |
| /// The opcode used by an `Ioctl`. |
| #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] |
| pub struct Opcode { |
| /// The raw opcode. |
| raw: RawOpcode, |
| } |
| |
| impl Opcode { |
| /// Create a new old `Opcode` from a raw opcode. |
| /// |
| /// Rather than being a composition of several attributes, old opcodes are |
| /// just numbers. In general most drivers follow stricter conventions, but |
| /// older drivers may still use this strategy. |
| #[inline] |
| pub const fn old(raw: RawOpcode) -> Self { |
| Self { raw } |
| } |
| |
| /// Create a new opcode from a direction, group, number and size. |
| /// |
| /// This corresponds to the C macro `_IOC(direction, group, number, size)` |
| #[cfg(any(linux_kernel, bsd))] |
| #[inline] |
| pub const fn from_components( |
| direction: Direction, |
| group: u8, |
| number: u8, |
| data_size: usize, |
| ) -> Self { |
| if data_size > RawOpcode::MAX as usize { |
| panic!("data size is too large"); |
| } |
| |
| Self::old(platform::compose_opcode( |
| direction, |
| group as RawOpcode, |
| number as RawOpcode, |
| data_size as RawOpcode, |
| )) |
| } |
| |
| /// Create a new non-mutating opcode from a group, a number and the type of |
| /// data. |
| /// |
| /// This corresponds to the C macro `_IO(group, number)` when `T` is zero |
| /// sized. |
| #[cfg(any(linux_kernel, bsd))] |
| #[inline] |
| pub const fn none<T>(group: u8, number: u8) -> Self { |
| Self::from_components(Direction::None, group, number, mem::size_of::<T>()) |
| } |
| |
| /// Create a new reading opcode from a group, a number and the type of |
| /// data. |
| /// |
| /// This corresponds to the C macro `_IOR(group, number, T)`. |
| #[cfg(any(linux_kernel, bsd))] |
| #[inline] |
| pub const fn read<T>(group: u8, number: u8) -> Self { |
| Self::from_components(Direction::Read, group, number, mem::size_of::<T>()) |
| } |
| |
| /// Create a new writing opcode from a group, a number and the type of |
| /// data. |
| /// |
| /// This corresponds to the C macro `_IOW(group, number, T)`. |
| #[cfg(any(linux_kernel, bsd))] |
| #[inline] |
| pub const fn write<T>(group: u8, number: u8) -> Self { |
| Self::from_components(Direction::Write, group, number, mem::size_of::<T>()) |
| } |
| |
| /// Create a new reading and writing opcode from a group, a number and the |
| /// type of data. |
| /// |
| /// This corresponds to the C macro `_IOWR(group, number, T)`. |
| #[cfg(any(linux_kernel, bsd))] |
| #[inline] |
| pub const fn read_write<T>(group: u8, number: u8) -> Self { |
| Self::from_components(Direction::ReadWrite, group, number, mem::size_of::<T>()) |
| } |
| |
| /// Get the raw opcode. |
| #[inline] |
| pub fn raw(self) -> RawOpcode { |
| self.raw |
| } |
| } |
| |
| /// The direction that an `ioctl` is going. |
| /// |
| /// Note that this is relative to userspace. `Read` means reading data from the |
| /// kernel, and write means the kernel writing data to userspace. |
| #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] |
| pub enum Direction { |
| /// None of the above. |
| None, |
| |
| /// Read data from the kernel. |
| Read, |
| |
| /// Write data to the kernel. |
| Write, |
| |
| /// Read and write data to the kernel. |
| ReadWrite, |
| } |
| |
| /// The type used by the `ioctl` to signify the output. |
| pub type IoctlOutput = c::c_int; |
| |
| /// The type used by the `ioctl` to signify the command. |
| pub type RawOpcode = _RawOpcode; |
| |
| // Under raw Linux, this is an `unsigned int`. |
| #[cfg(linux_raw)] |
| type _RawOpcode = c::c_uint; |
| |
| // On libc Linux with GNU libc or uclibc, this is an `unsigned long`. |
| #[cfg(all( |
| not(linux_raw), |
| target_os = "linux", |
| any(target_env = "gnu", target_env = "uclibc") |
| ))] |
| type _RawOpcode = c::c_ulong; |
| |
| // Musl uses `c_int`. |
| #[cfg(all( |
| not(linux_raw), |
| target_os = "linux", |
| not(target_env = "gnu"), |
| not(target_env = "uclibc") |
| ))] |
| type _RawOpcode = c::c_int; |
| |
| // Android uses `c_int`. |
| #[cfg(all(not(linux_raw), target_os = "android"))] |
| type _RawOpcode = c::c_int; |
| |
| // BSD, Haiku, Hurd, and Redox use `unsigned long`. |
| #[cfg(any(bsd, target_os = "redox", target_os = "haiku", target_os = "hurd"))] |
| type _RawOpcode = c::c_ulong; |
| |
| // AIX, Emscripten, Fuchsia, Solaris, and WASI use a `int`. |
| #[cfg(any( |
| solarish, |
| target_os = "aix", |
| target_os = "fuchsia", |
| target_os = "emscripten", |
| target_os = "wasi", |
| target_os = "nto" |
| ))] |
| type _RawOpcode = c::c_int; |
| |
| // ESP-IDF uses a `c_uint`. |
| #[cfg(target_os = "espidf")] |
| type _RawOpcode = c::c_uint; |
| |
| // Windows has `ioctlsocket`, which uses `i32`. |
| #[cfg(windows)] |
| type _RawOpcode = i32; |