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//! ```
228use cfg_if::cfg_if;
229
230#[cfg(any(linux_android, target_os = "redox"))]
231#[macro_use]
232mod linux;
233
234#[cfg(any(linux_android, target_os = "redox"))]
235pub use self::linux::*;
236
237#[cfg(any(bsd, solarish, target_os = "haiku",))]
238#[macro_use]
239mod bsd;
240
241#[cfg(any(bsd, solarish, target_os = "haiku",))]
242pub use self::bsd::*;
243
244/// Convert raw ioctl return value to a Nix result
245#[macro_export]
246#[doc(hidden)]
247macro_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)]
285macro_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)]
327macro_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)]
366macro_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)]
404macro_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)]
443macro_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)]
481macro_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
494cfg_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)]
613macro_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)]
652macro_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 unsafe {
659 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))
660 }
661 }
662 )
663}
664
665/// Generates a wrapper function for a "bad" ioctl that reads and writes data to the kernel.
666///
667/// The arguments to this macro are:
668///
669/// * The function name
670/// * The ioctl request code
671/// * The data type passed by this ioctl
672///
673/// The generated function has the following signature:
674///
675/// ```rust,ignore
676/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: *mut DATA_TYPE) -> Result<libc::c_int>
677/// ```
678///
679/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
680// TODO: Find an example for ioctl_readwrite_bad
681#[macro_export(local_inner_macros)]
682macro_rules! ioctl_readwrite_bad {
683 ($(#[$attr:meta])* $name:ident, $nr:expr, $ty:ty) => (
684 $(#[$attr])*
685 pub unsafe fn $name(fd: $crate::libc::c_int,
686 data: *mut $ty)
687 -> $crate::Result<$crate::libc::c_int> {
688 unsafe {
689 convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
690 }
691 }
692 )
693}
694
695/// Generates a wrapper function for an ioctl that reads an array of elements from the kernel.
696///
697/// The arguments to this macro are:
698///
699/// * The function name
700/// * The ioctl identifier
701/// * The ioctl sequence number
702/// * The data type passed by this ioctl
703///
704/// The generated function has the following signature:
705///
706/// ```rust,ignore
707/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &mut [DATA_TYPE]) -> Result<libc::c_int>
708/// ```
709///
710/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
711// TODO: Find an example for ioctl_read_buf
712#[macro_export(local_inner_macros)]
713macro_rules! ioctl_read_buf {
714 ($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => (
715 $(#[$attr])*
716 pub unsafe fn $name(fd: $crate::libc::c_int,
717 data: &mut [$ty])
718 -> $crate::Result<$crate::libc::c_int> {
719 unsafe {
720 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()))
721 }
722 }
723 )
724}
725
726/// Generates a wrapper function for an ioctl that writes an array of elements to the kernel.
727///
728/// The arguments to this macro are:
729///
730/// * The function name
731/// * The ioctl identifier
732/// * The ioctl sequence number
733/// * The data type passed by this ioctl
734///
735/// The generated function has the following signature:
736///
737/// ```rust,ignore
738/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &[DATA_TYPE]) -> Result<libc::c_int>
739/// ```
740///
741/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
742///
743/// # Examples
744///
745/// ```
746/// # #[macro_use] extern crate nix;
747/// const SPI_IOC_MAGIC: u8 = b'k'; // Defined in linux/spi/spidev.h
748/// const SPI_IOC_TYPE_MESSAGE: u8 = 0;
749/// # pub struct spi_ioc_transfer(u64);
750/// ioctl_write_buf!(spi_transfer, SPI_IOC_MAGIC, SPI_IOC_TYPE_MESSAGE, spi_ioc_transfer);
751/// # fn main() {}
752/// ```
753#[macro_export(local_inner_macros)]
754macro_rules! ioctl_write_buf {
755 ($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => (
756 $(#[$attr])*
757 pub unsafe fn $name(fd: $crate::libc::c_int,
758 data: &[$ty])
759 -> $crate::Result<$crate::libc::c_int> {
760 unsafe {
761 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()))
762 }
763 }
764 )
765}
766
767/// Generates a wrapper function for an ioctl that reads and writes an array of elements to the kernel.
768///
769/// The arguments to this macro are:
770///
771/// * The function name
772/// * The ioctl identifier
773/// * The ioctl sequence number
774/// * The data type passed by this ioctl
775///
776/// The generated function has the following signature:
777///
778/// ```rust,ignore
779/// pub unsafe fn FUNCTION_NAME(fd: libc::c_int, data: &mut [DATA_TYPE]) -> Result<libc::c_int>
780/// ```
781///
782/// For a more in-depth explanation of ioctls, see [`::sys::ioctl`](sys/ioctl/index.html).
783// TODO: Find an example for readwrite_buf
784#[macro_export(local_inner_macros)]
785macro_rules! ioctl_readwrite_buf {
786 ($(#[$attr:meta])* $name:ident, $ioty:expr, $nr:expr, $ty:ty) => (
787 $(#[$attr])*
788 pub unsafe fn $name(fd: $crate::libc::c_int,
789 data: &mut [$ty])
790 -> $crate::Result<$crate::libc::c_int> {
791 unsafe {
792 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()))
793 }
794 }
795 )
796}
797