| 1 |
//! Provide helpers for making ioctl system calls. |
| 2 |
//! |
| 3 |
//! This library is pretty low-level and messy. `ioctl` is not fun. |
| 4 |
//! |
| 5 |
//! What is an `ioctl`? |
| 6 |
//! =================== |
| 7 |
//! |
| 8 |
//! The `ioctl` syscall is the grab-bag syscall on POSIX systems. Don't want to add a new |
| 9 |
//! syscall? Make it an `ioctl`! `ioctl` refers to both the syscall, and the commands that can be |
| 10 |
//! sent with it. `ioctl` stands for "IO control", and the commands are always sent to a file |
| 11 |
//! descriptor. |
| 12 |
//! |
| 13 |
//! It is common to see `ioctl`s used for the following purposes: |
| 14 |
//! |
| 15 |
//! * Provide read/write access to out-of-band data related to a device such as configuration |
| 16 |
//! (for instance, setting serial port options) |
| 17 |
//! * Provide a mechanism for performing full-duplex data transfers (for instance, xfer on SPI |
| 18 |
//! devices). |
| 19 |
//! * Provide access to control functions on a device (for example, on Linux you can send |
| 20 |
//! commands like pause, resume, and eject to the CDROM device. |
| 21 |
//! * Do whatever else the device driver creator thought made most sense. |
| 22 |
//! |
| 23 |
//! `ioctl`s are synchronous system calls and are similar to read and write calls in that regard. |
| 24 |
//! They operate on file descriptors and have an identifier that specifies what the ioctl is. |
| 25 |
//! Additionally they may read or write data and therefore need to pass along a data pointer. |
| 26 |
//! Besides the semantics of the ioctls being confusing, the generation of this identifer can also |
| 27 |
//! be difficult. |
| 28 |
//! |
| 29 |
//! Historically `ioctl` numbers were arbitrary hard-coded values. In Linux (before 2.6) and some |
| 30 |
//! unices this has changed to a more-ordered system where the ioctl numbers are partitioned into |
| 31 |
//! subcomponents (For linux this is documented in |
| 32 |
//! [`Documentation/ioctl/ioctl-number.rst`](https://elixir.bootlin.com/linux/latest/source/Documentation/userspace-api/ioctl/ioctl-number.rst)): |
| 33 |
//! |
| 34 |
//! * Number: The actual ioctl ID |
| 35 |
//! * Type: A grouping of ioctls for a common purpose or driver |
| 36 |
//! * Size: The size in bytes of the data that will be transferred |
| 37 |
//! * Direction: Whether there is any data and if it's read, write, or both |
| 38 |
//! |
| 39 |
//! Newer drivers should not generate complete integer identifiers for their `ioctl`s instead |
| 40 |
//! preferring to use the 4 components above to generate the final ioctl identifier. Because of |
| 41 |
//! how old `ioctl`s are, however, there are many hard-coded `ioctl` identifiers. These are |
| 42 |
//! commonly referred to as "bad" in `ioctl` documentation. |
| 43 |
//! |
| 44 |
//! Defining `ioctl`s |
| 45 |
//! ================= |
| 46 |
//! |
| 47 |
//! This library provides several `ioctl_*!` macros for binding `ioctl`s. These generate public |
| 48 |
//! unsafe functions that can then be used for calling the ioctl. This macro has a few different |
| 49 |
//! ways it can be used depending on the specific ioctl you're working with. |
| 50 |
//! |
| 51 |
//! A simple `ioctl` is `SPI_IOC_RD_MODE`. This ioctl works with the SPI interface on Linux. This |
| 52 |
//! specific `ioctl` reads the mode of the SPI device as a `u8`. It's declared in |
| 53 |
//! `/include/uapi/linux/spi/spidev.h` as `_IOR(SPI_IOC_MAGIC, 1, __u8)`. Since it uses the `_IOR` |
| 54 |
//! macro, we know it's a `read` ioctl and can use the `ioctl_read!` macro as follows: |
| 55 |
//! |
| 56 |
//! ``` |
| 57 |
//! # #[macro_use] extern crate nix; |
| 58 |
//! const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h |
| 59 |
//! const SPI_IOC_TYPE_MODE: u8 = 1; |
| 60 |
//! ioctl_read!(spi_read_mode, SPI_IOC_MAGIC, SPI_IOC_TYPE_MODE, u8); |
| 61 |
//! # fn main() {} |
| 62 |
//! ``` |
| 63 |
//! |
| 64 |
//! This generates the function: |
| 65 |
//! |
| 66 |
//! ``` |
| 67 |
//! # #[macro_use] extern crate nix; |
| 68 |
//! # use std::mem; |
| 69 |
//! # use nix::{libc, Result}; |
| 70 |
//! # use nix::errno::Errno; |
| 71 |
//! # use nix::libc::c_int as c_int; |
| 72 |
//! # const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h |
| 73 |
//! # const SPI_IOC_TYPE_MODE: u8 = 1; |
| 74 |
//! pub unsafe fn spi_read_mode(fd: c_int, data: *mut u8) -> Result<c_int> { |
| 75 |
//! let res = unsafe { libc::ioctl(fd, request_code_read!(SPI_IOC_MAGIC, SPI_IOC_TYPE_MODE, mem::size_of::<u8>()), data) }; |
| 76 |
//! Errno::result(res) |
| 77 |
//! } |
| 78 |
//! # fn main() {} |
| 79 |
//! ``` |
| 80 |
//! |
| 81 |
//! The return value for the wrapper functions generated by the `ioctl_*!` macros are `nix::Error`s. |
| 82 |
//! These are generated by assuming the return value of the ioctl is `-1` on error and everything |
| 83 |
//! else is a valid return value. If this is not the case, `Result::map` can be used to map some |
| 84 |
//! of the range of "good" values (-Inf..-2, 0..Inf) into a smaller range in a helper function. |
| 85 |
//! |
| 86 |
//! Writing `ioctl`s generally use pointers as their data source and these should use the |
| 87 |
//! `ioctl_write_ptr!`. But in some cases an `int` is passed directly. For these `ioctl`s use the |
| 88 |
//! `ioctl_write_int!` macro. This variant does not take a type as the last argument: |
| 89 |
//! |
| 90 |
//! ``` |
| 91 |
//! # #[macro_use] extern crate nix; |
| 92 |
//! const HCI_IOC_MAGIC: u8 = b'k'; |
| 93 |
//! const HCI_IOC_HCIDEVUP: u8 = 1; |
| 94 |
//! ioctl_write_int!(hci_dev_up, HCI_IOC_MAGIC, HCI_IOC_HCIDEVUP); |
| 95 |
//! # fn main() {} |
| 96 |
//! ``` |
| 97 |
//! |
| 98 |
//! Some `ioctl`s don't transfer any data, and those should use `ioctl_none!`. This macro |
| 99 |
//! doesn't take a type and so it is declared similar to the `write_int` variant shown above. |
| 100 |
//! |
| 101 |
//! The mode for a given `ioctl` should be clear from the documentation if it has good |
| 102 |
//! documentation. Otherwise it will be clear based on the macro used to generate the `ioctl` |
| 103 |
//! number where `_IO`, `_IOR`, `_IOW`, and `_IOWR` map to "none", "read", "write_*", and "readwrite" |
| 104 |
//! respectively. To determine the specific `write_` variant to use you'll need to find |
| 105 |
//! what the argument type is supposed to be. If it's an `int`, then `write_int` should be used, |
| 106 |
//! otherwise it should be a pointer and `write_ptr` should be used. On Linux the |
| 107 |
//! [`ioctl_list` man page](https://man7.org/linux/man-pages/man2/ioctl_list.2.html) describes a |
| 108 |
//! large number of `ioctl`s and describes their argument data type. |
| 109 |
//! |
| 110 |
//! Using "bad" `ioctl`s |
| 111 |
//! -------------------- |
| 112 |
//! |
| 113 |
//! As mentioned earlier, there are many old `ioctl`s that do not use the newer method of |
| 114 |
//! generating `ioctl` numbers and instead use hardcoded values. These can be used with the |
| 115 |
//! `ioctl_*_bad!` macros. This naming comes from the Linux kernel which refers to these |
| 116 |
//! `ioctl`s as "bad". These are a different variant as they bypass calling the macro that generates |
| 117 |
//! the ioctl number and instead use the defined value directly. |
| 118 |
//! |
| 119 |
//! For example the `TCGETS` `ioctl` reads a `termios` data structure for a given file descriptor. |
| 120 |
//! It's defined as `0x5401` in `ioctls.h` on Linux and can be implemented as: |
| 121 |
//! |
| 122 |
//! ``` |
| 123 |
//! # #[macro_use] extern crate nix; |
| 124 |
//! # #[cfg(linux_android)] |
| 125 |
//! # use nix::libc::TCGETS as TCGETS; |
| 126 |
//! # #[cfg(linux_android)] |
| 127 |
//! # use nix::libc::termios as termios; |
| 128 |
//! # #[cfg(linux_android)] |
| 129 |
//! ioctl_read_bad!(tcgets, TCGETS, termios); |
| 130 |
//! # fn main() {} |
| 131 |
//! ``` |
| 132 |
//! |
| 133 |
//! The generated function has the same form as that generated by `ioctl_read!`: |
| 134 |
//! |
| 135 |
//! ```text |
| 136 |
//! pub unsafe fn tcgets(fd: c_int, data: *mut termios) -> Result<c_int>; |
| 137 |
//! ``` |
| 138 |
//! |
| 139 |
//! Working with Arrays |
| 140 |
//! ------------------- |
| 141 |
//! |
| 142 |
//! Some `ioctl`s work with entire arrays of elements. These are supported by the `ioctl_*_buf` |
| 143 |
//! family of macros: `ioctl_read_buf`, `ioctl_write_buf`, and `ioctl_readwrite_buf`. Note that |
| 144 |
//! there are no "bad" versions for working with buffers. The generated functions include a `len` |
| 145 |
//! argument to specify the number of elements (where the type of each element is specified in the |
| 146 |
//! macro). |
| 147 |
//! |
| 148 |
//! Again looking to the SPI `ioctl`s on Linux for an example, there is a `SPI_IOC_MESSAGE` `ioctl` |
| 149 |
//! that queues up multiple SPI messages by writing an entire array of `spi_ioc_transfer` structs. |
| 150 |
//! `linux/spi/spidev.h` defines a macro to calculate the `ioctl` number like: |
| 151 |
//! |
| 152 |
//! ```C |
| 153 |
//! #define SPI_IOC_MAGIC 'k' |
| 154 |
//! #define SPI_MSGSIZE(N) ... |
| 155 |
//! #define SPI_IOC_MESSAGE(N) _IOW(SPI_IOC_MAGIC, 0, char[SPI_MSGSIZE(N)]) |
| 156 |
//! ``` |
| 157 |
//! |
| 158 |
//! The `SPI_MSGSIZE(N)` calculation is already handled by the `ioctl_*!` macros, so all that's |
| 159 |
//! needed to define this `ioctl` is: |
| 160 |
//! |
| 161 |
//! ``` |
| 162 |
//! # #[macro_use] extern crate nix; |
| 163 |
//! const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h |
| 164 |
//! const SPI_IOC_TYPE_MESSAGE: u8 = 0; |
| 165 |
//! # pub struct spi_ioc_transfer(u64); |
| 166 |
//! ioctl_write_buf!(spi_transfer, SPI_IOC_MAGIC, SPI_IOC_TYPE_MESSAGE, spi_ioc_transfer); |
| 167 |
//! # fn main() {} |
| 168 |
//! ``` |
| 169 |
//! |
| 170 |
//! This generates a function like: |
| 171 |
//! |
| 172 |
//! ``` |
| 173 |
//! # #[macro_use] extern crate nix; |
| 174 |
//! # use std::mem; |
| 175 |
//! # use nix::{libc, Result}; |
| 176 |
//! # use nix::errno::Errno; |
| 177 |
//! # use nix::libc::c_int as c_int; |
| 178 |
//! # const SPI_IOC_MAGIC: u8 = b'k'; |
| 179 |
//! # const SPI_IOC_TYPE_MESSAGE: u8 = 0; |
| 180 |
//! # pub struct spi_ioc_transfer(u64); |
| 181 |
//! pub unsafe fn spi_message(fd: c_int, data: &mut [spi_ioc_transfer]) -> Result<c_int> { |
| 182 |
//! let res = unsafe { |
| 183 |
//! libc::ioctl( |
| 184 |
//! fd, |
| 185 |
//! request_code_write!(SPI_IOC_MAGIC, SPI_IOC_TYPE_MESSAGE, data.len() * mem::size_of::<spi_ioc_transfer>()), |
| 186 |
//! data |
| 187 |
//! ) |
| 188 |
//! }; |
| 189 |
//! Errno::result(res) |
| 190 |
//! } |
| 191 |
//! # fn main() {} |
| 192 |
//! ``` |
| 193 |
//! |
| 194 |
//! Finding `ioctl` Documentation |
| 195 |
//! ----------------------------- |
| 196 |
//! |
| 197 |
//! For Linux, look at your system's headers. For example, `/usr/include/linux/input.h` has a lot |
| 198 |
//! of lines defining macros which use `_IO`, `_IOR`, `_IOW`, `_IOC`, and `_IOWR`. Some `ioctl`s are |
| 199 |
//! documented directly in the headers defining their constants, but others have more extensive |
| 200 |
//! documentation in man pages (like termios' `ioctl`s which are in `tty_ioctl(4)`). |
| 201 |
//! |
| 202 |
//! Documenting the Generated Functions |
| 203 |
//! =================================== |
| 204 |
//! |
| 205 |
//! In many cases, users will wish for the functions generated by the `ioctl` |
| 206 |
//! macro to be public and documented. For this reason, the generated functions |
| 207 |
//! are public by default. If you wish to hide the ioctl, you will need to put |
| 208 |
//! them in a private module. |
| 209 |
//! |
| 210 |
//! For documentation, it is possible to use doc comments inside the `ioctl_*!` macros. Here is an |
| 211 |
//! example : |
| 212 |
//! |
| 213 |
//! ``` |
| 214 |
//! # #[macro_use] extern crate nix; |
| 215 |
//! # use nix::libc::c_int; |
| 216 |
//! ioctl_read! { |
| 217 |
//! /// Make the given terminal the controlling terminal of the calling process. The calling |
| 218 |
//! /// process must be a session leader and not have a controlling terminal already. If the |
| 219 |
//! /// terminal is already the controlling terminal of a different session group then the |
| 220 |
//! /// ioctl will fail with **EPERM**, unless the caller is root (more precisely: has the |
| 221 |
//! /// **CAP_SYS_ADMIN** capability) and arg equals 1, in which case the terminal is stolen |
| 222 |
//! /// and all processes that had it as controlling terminal lose it. |
| 223 |
//! tiocsctty, b't', 19, c_int |
| 224 |
//! } |
| 225 |
//! |
| 226 |
//! # fn main() {} |
| 227 |
//! ``` |
| 228 |
use cfg_if::cfg_if; |
| 229 |
|
| 230 |
#[cfg(any(linux_android, target_os = "fuchsia", target_os = "redox"))] |
| 231 |
#[macro_use] |
| 232 |
mod linux; |
| 233 |
|
| 234 |
#[cfg(any(linux_android, target_os = "fuchsia", target_os = "redox"))] |
| 235 |
pub use self::linux::*; |
| 236 |
|
| 237 |
#[cfg(any(bsd, solarish, target_os = "haiku",))] |
| 238 |
#[macro_use] |
| 239 |
mod bsd; |
| 240 |
|
| 241 |
#[cfg(any(bsd, solarish, target_os = "haiku",))] |
| 242 |
pub use self::bsd::*; |
| 243 |
|
| 244 |
/// Convert raw ioctl return value to a Nix result |
| 245 |
#[macro_export] |
| 246 |
#[doc(hidden)] |
| 247 |
macro_rules! convert_ioctl_res { |
| 248 |
($w:expr) => {{ |
| 249 |
$crate::errno::Errno::result($w) |
| 250 |
}}; |
| 251 |
} |
| 252 |
|
| 253 |
/// Generates a wrapper function for an ioctl that passes no data to the kernel. |
| 254 |
/// |
| 255 |
/// The arguments to this macro are: |
| 256 |
/// |
| 257 |
/// * The function name |
| 258 |
/// * The ioctl identifier |
| 259 |
/// * The ioctl sequence number |
| 260 |
/// |
| 261 |
/// The generated function has the following signature: |
| 262 |
/// |
| 263 |
/// ```rust,ignore |
| 264 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int) -> Result<libc::c_int> |
| 265 |
/// ``` |
| 266 |
/// |
| 267 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 268 |
/// |
| 269 |
/// # Example |
| 270 |
/// |
| 271 |
/// The `videodev2` driver on Linux defines the `log_status` `ioctl` as: |
| 272 |
/// |
| 273 |
/// ```C |
| 274 |
/// #define VIDIOC_LOG_STATUS _IO('V', 70) |
| 275 |
/// ``` |
| 276 |
/// |
| 277 |
/// This can be implemented in Rust like: |
| 278 |
/// |
| 279 |
/// ```no_run |
| 280 |
/// # #[macro_use] extern crate nix; |
| 281 |
/// ioctl_none!(log_status, b'V', 70); |
| 282 |
/// fn main() {} |
| 283 |
/// ``` |
| 284 |
#[macro_export(local_inner_macros)] |
| 285 |
macro_rules! ioctl_none { |
| 286 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr) => ( |
| 287 |
$(#[$attr])* |
| 288 |
pub unsafe fn $name(fd: $crate::libc::c_int) |
| 289 |
-> $crate::Result<$crate::libc::c_int> { |
| 290 |
unsafe { |
| 291 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_none!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type)) |
| 292 |
} |
| 293 |
} |
| 294 |
) |
| 295 |
} |
| 296 |
|
| 297 |
/// Generates a wrapper function for a "bad" ioctl that passes no data to the kernel. |
| 298 |
/// |
| 299 |
/// The arguments to this macro are: |
| 300 |
/// |
| 301 |
/// * The function name |
| 302 |
/// * The ioctl request code |
| 303 |
/// |
| 304 |
/// The generated function has the following signature: |
| 305 |
/// |
| 306 |
/// ```rust,ignore |
| 307 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int) -> Result<libc::c_int> |
| 308 |
/// ``` |
| 309 |
/// |
| 310 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 311 |
/// |
| 312 |
/// # Example |
| 313 |
/// |
| 314 |
/// ```no_run |
| 315 |
/// # #[macro_use] extern crate nix; |
| 316 |
/// # use libc::TIOCNXCL; |
| 317 |
/// # use std::fs::File; |
| 318 |
/// # use std::os::unix::io::AsRawFd; |
| 319 |
/// ioctl_none_bad!(tiocnxcl, TIOCNXCL); |
| 320 |
/// fn main() { |
| 321 |
/// let file = File::open("/dev/ttyUSB0").unwrap(); |
| 322 |
/// unsafe { tiocnxcl(file.as_raw_fd()) }.unwrap(); |
| 323 |
/// } |
| 324 |
/// ``` |
| 325 |
// TODO: add an example using request_code_*!() |
| 326 |
#[macro_export(local_inner_macros)] |
| 327 |
macro_rules! ioctl_none_bad { |
| 328 |
($(#[$attr:meta])* $name:ident, $nr:expr) => ( |
| 329 |
$(#[$attr])* |
| 330 |
pub unsafe fn $name(fd: $crate::libc::c_int) |
| 331 |
-> $crate::Result<$crate::libc::c_int> { |
| 332 |
unsafe { |
| 333 |
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type)) |
| 334 |
} |
| 335 |
} |
| 336 |
) |
| 337 |
} |
| 338 |
|
| 339 |
/// Generates a wrapper function for an ioctl that reads data from the kernel. |
| 340 |
/// |
| 341 |
/// The arguments to this macro are: |
| 342 |
/// |
| 343 |
/// * The function name |
| 344 |
/// * The ioctl identifier |
| 345 |
/// * The ioctl sequence number |
| 346 |
/// * The data type passed by this ioctl |
| 347 |
/// |
| 348 |
/// The generated function has the following signature: |
| 349 |
/// |
| 350 |
/// ```rust,ignore |
| 351 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *mut DATA_TYPE) -> Result<libc::c_int> |
| 352 |
/// ``` |
| 353 |
/// |
| 354 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 355 |
/// |
| 356 |
/// # Example |
| 357 |
/// |
| 358 |
/// ``` |
| 359 |
/// # #[macro_use] extern crate nix; |
| 360 |
/// const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h |
| 361 |
/// const SPI_IOC_TYPE_MODE: u8 = 1; |
| 362 |
/// ioctl_read!(spi_read_mode, SPI_IOC_MAGIC, SPI_IOC_TYPE_MODE, u8); |
| 363 |
/// # fn main() {} |
| 364 |
/// ``` |
| 365 |
#[macro_export(local_inner_macros)] |
| 366 |
macro_rules! ioctl_read { |
| 367 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 368 |
$(#[$attr])* |
| 369 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 370 |
data: *mut $ty) |
| 371 |
-> $crate::Result<$crate::libc::c_int> { |
| 372 |
unsafe { |
| 373 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_read!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data)) |
| 374 |
} |
| 375 |
} |
| 376 |
) |
| 377 |
} |
| 378 |
|
| 379 |
/// Generates a wrapper function for a "bad" ioctl that reads data from the kernel. |
| 380 |
/// |
| 381 |
/// The arguments to this macro are: |
| 382 |
/// |
| 383 |
/// * The function name |
| 384 |
/// * The ioctl request code |
| 385 |
/// * The data type passed by this ioctl |
| 386 |
/// |
| 387 |
/// The generated function has the following signature: |
| 388 |
/// |
| 389 |
/// ```rust,ignore |
| 390 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *mut DATA_TYPE) -> Result<libc::c_int> |
| 391 |
/// ``` |
| 392 |
/// |
| 393 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 394 |
/// |
| 395 |
/// # Example |
| 396 |
/// |
| 397 |
/// ``` |
| 398 |
/// # #[macro_use] extern crate nix; |
| 399 |
/// # #[cfg(linux_android)] |
| 400 |
/// ioctl_read_bad!(tcgets, libc::TCGETS, libc::termios); |
| 401 |
/// # fn main() {} |
| 402 |
/// ``` |
| 403 |
#[macro_export(local_inner_macros)] |
| 404 |
macro_rules! ioctl_read_bad { |
| 405 |
($(#[$attr:meta])* $name:ident, $nr:expr, $ty:ty) => ( |
| 406 |
$(#[$attr])* |
| 407 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 408 |
data: *mut $ty) |
| 409 |
-> $crate::Result<$crate::libc::c_int> { |
| 410 |
unsafe { |
| 411 |
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data)) |
| 412 |
} |
| 413 |
} |
| 414 |
) |
| 415 |
} |
| 416 |
|
| 417 |
/// Generates a wrapper function for an ioctl that writes data through a pointer to the kernel. |
| 418 |
/// |
| 419 |
/// The arguments to this macro are: |
| 420 |
/// |
| 421 |
/// * The function name |
| 422 |
/// * The ioctl identifier |
| 423 |
/// * The ioctl sequence number |
| 424 |
/// * The data type passed by this ioctl |
| 425 |
/// |
| 426 |
/// The generated function has the following signature: |
| 427 |
/// |
| 428 |
/// ```rust,ignore |
| 429 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *const DATA_TYPE) -> Result<libc::c_int> |
| 430 |
/// ``` |
| 431 |
/// |
| 432 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 433 |
/// |
| 434 |
/// # Example |
| 435 |
/// |
| 436 |
/// ``` |
| 437 |
/// # #[macro_use] extern crate nix; |
| 438 |
/// # pub struct v4l2_audio {} |
| 439 |
/// ioctl_write_ptr!(s_audio, b'V', 34, v4l2_audio); |
| 440 |
/// # fn main() {} |
| 441 |
/// ``` |
| 442 |
#[macro_export(local_inner_macros)] |
| 443 |
macro_rules! ioctl_write_ptr { |
| 444 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 445 |
$(#[$attr])* |
| 446 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 447 |
data: *const $ty) |
| 448 |
-> $crate::Result<$crate::libc::c_int> { |
| 449 |
unsafe { |
| 450 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data)) |
| 451 |
} |
| 452 |
} |
| 453 |
) |
| 454 |
} |
| 455 |
|
| 456 |
/// Generates a wrapper function for a "bad" ioctl that writes data through a pointer to the kernel. |
| 457 |
/// |
| 458 |
/// The arguments to this macro are: |
| 459 |
/// |
| 460 |
/// * The function name |
| 461 |
/// * The ioctl request code |
| 462 |
/// * The data type passed by this ioctl |
| 463 |
/// |
| 464 |
/// The generated function has the following signature: |
| 465 |
/// |
| 466 |
/// ```rust,ignore |
| 467 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *const DATA_TYPE) -> Result<libc::c_int> |
| 468 |
/// ``` |
| 469 |
/// |
| 470 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 471 |
/// |
| 472 |
/// # Example |
| 473 |
/// |
| 474 |
/// ``` |
| 475 |
/// # #[macro_use] extern crate nix; |
| 476 |
/// # #[cfg(linux_android)] |
| 477 |
/// ioctl_write_ptr_bad!(tcsets, libc::TCSETS, libc::termios); |
| 478 |
/// # fn main() {} |
| 479 |
/// ``` |
| 480 |
#[macro_export(local_inner_macros)] |
| 481 |
macro_rules! ioctl_write_ptr_bad { |
| 482 |
($(#[$attr:meta])* $name:ident, $nr:expr, $ty:ty) => ( |
| 483 |
$(#[$attr])* |
| 484 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 485 |
data: *const $ty) |
| 486 |
-> $crate::Result<$crate::libc::c_int> { |
| 487 |
unsafe { |
| 488 |
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data)) |
| 489 |
} |
| 490 |
} |
| 491 |
) |
| 492 |
} |
| 493 |
|
| 494 |
cfg_if! { |
| 495 |
if #[cfg(freebsdlike)] { |
| 496 |
/// Generates a wrapper function for a ioctl that writes an integer to the kernel. |
| 497 |
/// |
| 498 |
/// The arguments to this macro are: |
| 499 |
/// |
| 500 |
/// * The function name |
| 501 |
/// * The ioctl identifier |
| 502 |
/// * The ioctl sequence number |
| 503 |
/// |
| 504 |
/// The generated function has the following signature: |
| 505 |
/// |
| 506 |
/// ```rust,ignore |
| 507 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: nix::sys::ioctl::ioctl_param_type) -> Result<libc::c_int> |
| 508 |
/// ``` |
| 509 |
/// |
| 510 |
/// `nix::sys::ioctl::ioctl_param_type` depends on the OS: |
| 511 |
/// * BSD - `libc::c_int` |
| 512 |
/// * Linux - `libc::c_ulong` |
| 513 |
/// |
| 514 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 515 |
/// |
| 516 |
/// # Example |
| 517 |
/// |
| 518 |
/// ``` |
| 519 |
/// # #[macro_use] extern crate nix; |
| 520 |
/// ioctl_write_int!(vt_activate, b'v', 4); |
| 521 |
/// # fn main() {} |
| 522 |
/// ``` |
| 523 |
#[macro_export(local_inner_macros)] |
| 524 |
macro_rules! ioctl_write_int { |
| 525 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr) => ( |
| 526 |
$(#[$attr])* |
| 527 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 528 |
data: $crate::sys::ioctl::ioctl_param_type) |
| 529 |
-> $crate::Result<$crate::libc::c_int> { |
| 530 |
unsafe { |
| 531 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write_int!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type, data)) |
| 532 |
} |
| 533 |
} |
| 534 |
) |
| 535 |
} |
| 536 |
} else { |
| 537 |
/// Generates a wrapper function for a ioctl that writes an integer to the kernel. |
| 538 |
/// |
| 539 |
/// The arguments to this macro are: |
| 540 |
/// |
| 541 |
/// * The function name |
| 542 |
/// * The ioctl identifier |
| 543 |
/// * The ioctl sequence number |
| 544 |
/// |
| 545 |
/// The generated function has the following signature: |
| 546 |
/// |
| 547 |
/// ```rust,ignore |
| 548 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: nix::sys::ioctl::ioctl_param_type) -> Result<libc::c_int> |
| 549 |
/// ``` |
| 550 |
/// |
| 551 |
/// `nix::sys::ioctl::ioctl_param_type` depends on the OS: |
| 552 |
/// * BSD - `libc::c_int` |
| 553 |
/// * Linux - `libc::c_ulong` |
| 554 |
/// |
| 555 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 556 |
/// |
| 557 |
/// # Example |
| 558 |
/// |
| 559 |
/// ``` |
| 560 |
/// # #[macro_use] extern crate nix; |
| 561 |
/// const HCI_IOC_MAGIC: u8 = b'k'; |
| 562 |
/// const HCI_IOC_HCIDEVUP: u8 = 1; |
| 563 |
/// ioctl_write_int!(hci_dev_up, HCI_IOC_MAGIC, HCI_IOC_HCIDEVUP); |
| 564 |
/// # fn main() {} |
| 565 |
/// ``` |
| 566 |
#[macro_export(local_inner_macros)] |
| 567 |
macro_rules! ioctl_write_int { |
| 568 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr) => ( |
| 569 |
$(#[$attr])* |
| 570 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 571 |
data: $crate::sys::ioctl::ioctl_param_type) |
| 572 |
-> $crate::Result<$crate::libc::c_int> { |
| 573 |
unsafe { |
| 574 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, ::std::mem::size_of::<$crate::libc::c_int>()) as $crate::sys::ioctl::ioctl_num_type, data)) |
| 575 |
} |
| 576 |
} |
| 577 |
) |
| 578 |
} |
| 579 |
} |
| 580 |
} |
| 581 |
|
| 582 |
/// Generates a wrapper function for a "bad" ioctl that writes an integer to the kernel. |
| 583 |
/// |
| 584 |
/// The arguments to this macro are: |
| 585 |
/// |
| 586 |
/// * The function name |
| 587 |
/// * The ioctl request code |
| 588 |
/// |
| 589 |
/// The generated function has the following signature: |
| 590 |
/// |
| 591 |
/// ```rust,ignore |
| 592 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: libc::c_int) -> Result<libc::c_int> |
| 593 |
/// ``` |
| 594 |
/// |
| 595 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 596 |
/// |
| 597 |
/// # Examples |
| 598 |
/// |
| 599 |
/// ``` |
| 600 |
/// # #[macro_use] extern crate nix; |
| 601 |
/// # #[cfg(linux_android)] |
| 602 |
/// ioctl_write_int_bad!(tcsbrk, libc::TCSBRK); |
| 603 |
/// # fn main() {} |
| 604 |
/// ``` |
| 605 |
/// |
| 606 |
/// ```rust |
| 607 |
/// # #[macro_use] extern crate nix; |
| 608 |
/// const KVMIO: u8 = 0xAE; |
| 609 |
/// ioctl_write_int_bad!(kvm_create_vm, request_code_none!(KVMIO, 0x03)); |
| 610 |
/// # fn main() {} |
| 611 |
/// ``` |
| 612 |
#[macro_export(local_inner_macros)] |
| 613 |
macro_rules! ioctl_write_int_bad { |
| 614 |
($(#[$attr:meta])* $name:ident, $nr:expr) => ( |
| 615 |
$(#[$attr])* |
| 616 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 617 |
data: $crate::libc::c_int) |
| 618 |
-> $crate::Result<$crate::libc::c_int> { |
| 619 |
unsafe { |
| 620 |
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data)) |
| 621 |
} |
| 622 |
} |
| 623 |
) |
| 624 |
} |
| 625 |
|
| 626 |
/// Generates a wrapper function for an ioctl that reads and writes data to the kernel. |
| 627 |
/// |
| 628 |
/// The arguments to this macro are: |
| 629 |
/// |
| 630 |
/// * The function name |
| 631 |
/// * The ioctl identifier |
| 632 |
/// * The ioctl sequence number |
| 633 |
/// * The data type passed by this ioctl |
| 634 |
/// |
| 635 |
/// The generated function has the following signature: |
| 636 |
/// |
| 637 |
/// ```rust,ignore |
| 638 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *mut DATA_TYPE) -> Result<libc::c_int> |
| 639 |
/// ``` |
| 640 |
/// |
| 641 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 642 |
/// |
| 643 |
/// # Example |
| 644 |
/// |
| 645 |
/// ``` |
| 646 |
/// # #[macro_use] extern crate nix; |
| 647 |
/// # pub struct v4l2_audio {} |
| 648 |
/// ioctl_readwrite!(enum_audio, b'V', 65, v4l2_audio); |
| 649 |
/// # fn main() {} |
| 650 |
/// ``` |
| 651 |
#[macro_export(local_inner_macros)] |
| 652 |
macro_rules! ioctl_readwrite { |
| 653 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 654 |
$(#[$attr])* |
| 655 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 656 |
data: *mut $ty) |
| 657 |
-> $crate::Result<$crate::libc::c_int> { |
| 658 |
let ioty = $ioty; |
| 659 |
let nr = $nr; |
| 660 |
unsafe { |
| 661 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_readwrite!(ioty, nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data)) |
| 662 |
} |
| 663 |
} |
| 664 |
) |
| 665 |
} |
| 666 |
|
| 667 |
/// Generates a wrapper function for a "bad" ioctl that reads and writes data to the kernel. |
| 668 |
/// |
| 669 |
/// The arguments to this macro are: |
| 670 |
/// |
| 671 |
/// * The function name |
| 672 |
/// * The ioctl request code |
| 673 |
/// * The data type passed by this ioctl |
| 674 |
/// |
| 675 |
/// The generated function has the following signature: |
| 676 |
/// |
| 677 |
/// ```rust,ignore |
| 678 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *mut DATA_TYPE) -> Result<libc::c_int> |
| 679 |
/// ``` |
| 680 |
/// |
| 681 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 682 |
// TODO: Find an example for ioctl_readwrite_bad |
| 683 |
#[macro_export(local_inner_macros)] |
| 684 |
macro_rules! ioctl_readwrite_bad { |
| 685 |
($(#[$attr:meta])* $name:ident, $nr:expr, $ty:ty) => ( |
| 686 |
$(#[$attr])* |
| 687 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 688 |
data: *mut $ty) |
| 689 |
-> $crate::Result<$crate::libc::c_int> { |
| 690 |
unsafe { |
| 691 |
convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data)) |
| 692 |
} |
| 693 |
} |
| 694 |
) |
| 695 |
} |
| 696 |
|
| 697 |
/// Generates a wrapper function for an ioctl that reads an array of elements from the kernel. |
| 698 |
/// |
| 699 |
/// The arguments to this macro are: |
| 700 |
/// |
| 701 |
/// * The function name |
| 702 |
/// * The ioctl identifier |
| 703 |
/// * The ioctl sequence number |
| 704 |
/// * The data type passed by this ioctl |
| 705 |
/// |
| 706 |
/// The generated function has the following signature: |
| 707 |
/// |
| 708 |
/// ```rust,ignore |
| 709 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &mut [DATA_TYPE]) -> Result<libc::c_int> |
| 710 |
/// ``` |
| 711 |
/// |
| 712 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 713 |
// TODO: Find an example for ioctl_read_buf |
| 714 |
#[macro_export(local_inner_macros)] |
| 715 |
macro_rules! ioctl_read_buf { |
| 716 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 717 |
$(#[$attr])* |
| 718 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 719 |
data: &mut [$ty]) |
| 720 |
-> $crate::Result<$crate::libc::c_int> { |
| 721 |
unsafe { |
| 722 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_read!($ioty, $nr, ::std::mem::size_of_val(data)) as $crate::sys::ioctl::ioctl_num_type, data.as_mut_ptr())) |
| 723 |
} |
| 724 |
} |
| 725 |
) |
| 726 |
} |
| 727 |
|
| 728 |
/// Generates a wrapper function for an ioctl that writes an array of elements to the kernel. |
| 729 |
/// |
| 730 |
/// The arguments to this macro are: |
| 731 |
/// |
| 732 |
/// * The function name |
| 733 |
/// * The ioctl identifier |
| 734 |
/// * The ioctl sequence number |
| 735 |
/// * The data type passed by this ioctl |
| 736 |
/// |
| 737 |
/// The generated function has the following signature: |
| 738 |
/// |
| 739 |
/// ```rust,ignore |
| 740 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &[DATA_TYPE]) -> Result<libc::c_int> |
| 741 |
/// ``` |
| 742 |
/// |
| 743 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 744 |
/// |
| 745 |
/// # Examples |
| 746 |
/// |
| 747 |
/// ``` |
| 748 |
/// # #[macro_use] extern crate nix; |
| 749 |
/// const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h |
| 750 |
/// const SPI_IOC_TYPE_MESSAGE: u8 = 0; |
| 751 |
/// # pub struct spi_ioc_transfer(u64); |
| 752 |
/// ioctl_write_buf!(spi_transfer, SPI_IOC_MAGIC, SPI_IOC_TYPE_MESSAGE, spi_ioc_transfer); |
| 753 |
/// # fn main() {} |
| 754 |
/// ``` |
| 755 |
#[macro_export(local_inner_macros)] |
| 756 |
macro_rules! ioctl_write_buf { |
| 757 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 758 |
$(#[$attr])* |
| 759 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 760 |
data: &[$ty]) |
| 761 |
-> $crate::Result<$crate::libc::c_int> { |
| 762 |
unsafe { |
| 763 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_write!($ioty, $nr, ::std::mem::size_of_val(data)) as $crate::sys::ioctl::ioctl_num_type, data.as_ptr())) |
| 764 |
} |
| 765 |
} |
| 766 |
) |
| 767 |
} |
| 768 |
|
| 769 |
/// Generates a wrapper function for an ioctl that reads and writes an array of elements to the kernel. |
| 770 |
/// |
| 771 |
/// The arguments to this macro are: |
| 772 |
/// |
| 773 |
/// * The function name |
| 774 |
/// * The ioctl identifier |
| 775 |
/// * The ioctl sequence number |
| 776 |
/// * The data type passed by this ioctl |
| 777 |
/// |
| 778 |
/// The generated function has the following signature: |
| 779 |
/// |
| 780 |
/// ```rust,ignore |
| 781 |
/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &mut [DATA_TYPE]) -> Result<libc::c_int> |
| 782 |
/// ``` |
| 783 |
/// |
| 784 |
/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html). |
| 785 |
// TODO: Find an example for readwrite_buf |
| 786 |
#[macro_export(local_inner_macros)] |
| 787 |
macro_rules! ioctl_readwrite_buf { |
| 788 |
($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => ( |
| 789 |
$(#[$attr])* |
| 790 |
pub unsafe fn $name(fd: $crate::libc::c_int, |
| 791 |
data: &mut [$ty]) |
| 792 |
-> $crate::Result<$crate::libc::c_int> { |
| 793 |
unsafe { |
| 794 |
convert_ioctl_res!($crate::libc::ioctl(fd, request_code_readwrite!($ioty, $nr, ::std::mem::size_of_val(data)) as $crate::sys::ioctl::ioctl_num_type, data.as_mut_ptr())) |
| 795 |
} |
| 796 |
} |
| 797 |
) |
| 798 |
} |