Add 'bad' prefexis for read, write, and readwrite ioctls

Author: Susurrus

src/sys/ioctl/mod.rs

@@ -87,14 +87,15 @@
 //!
 //! More examples on using `ioctl!` can be found in the [rust-spidev crate](https://github.com/rust-embedded/rust-spidev).
 //!
-//! ```text
-//! pub unsafe fn $NAME(fd: c_int, val: *mut u8, len: usize) -> Result<c_int>;
-//! ```
+//! Using hard-coded ioctl numbers
+//! ------------------------------
 //!
 //! As mentioned earlier, there are many old `ioctl`s that do not use the newer method of
 //! generating `ioctl` numbers and instead use hardcoded values. These can be used with the `bad`
 //! form of the `ioctl!` macro (there is no data transfer direction used with `bad`). The naming of
-//! this comes from the Linux kernel which refers to these `ioctl`s as "bad".
+//! this comes from the Linux kernel which refers to these `ioctl`s as "bad". These are a different
+//! form as they bypass calling the macro that generates that ioctl number and instead use the
+//! defined value directly. These are supported by the `bad` prefix with the `ioctl!` macro.
 //!
 //! For example the `TCGETS` `ioctl` reads a `termios` data structure for a given file descriptor.
 //! It can be implemented as:
@@ -104,18 +105,20 @@
 //! # #[cfg(any(target_os = "android", target_os = "linux"))]
 //! # use nix::libc::TCGETS as TCGETS;
 //! # #[cfg(any(target_os = "android", target_os = "linux"))]
-//! ioctl!(bad tcgets with TCGETS);
+//! # use nix::libc::termios as termios;
+//! # #[cfg(any(target_os = "android", target_os = "linux"))]
+//! ioctl!(bad read tcgets with TCGETS; termios);
 //! # fn main() {}
 //! ```
 //!
 //! The generated function has the same form as that generated by `read`:
 //!
 //! ```text
-//! pub unsafe fn tcgets(fd: c_int, val: *mut u8) -> Result<c_int>;
+//! pub unsafe fn tcgets(fd: c_int, val: *mut termios) -> Result<c_int>;
 //! ```
 //!
-//! There is also a `bad none` form for use with hard-coded `ioctl`s that do not transfer data.
-//! The `TIOCEXCL` `ioctl` that's part of the termios API can be implemented as:
+//! There is also a `bad none`, `bad write`, and `bad readwrite` form that work similar to the
+//! standard `none`, `write`, and `readwrite` forms.
 //!
 //! ```
 //! # #[macro_use] extern crate nix;
@@ -164,17 +167,31 @@ macro_rules! convert_ioctl_res {
 /// Generates ioctl functions. See [::sys::ioctl](sys/ioctl/index.html).
 #[macro_export]
 macro_rules! ioctl {
-    (bad $name:ident with $nr:expr) => (
+    (bad none $name:ident with $nr:expr) => (
+        pub unsafe fn $name(fd: $crate::libc::c_int)
+                            -> $crate::Result<$crate::libc::c_int> {
+            convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type))
+        }
+        );
+    (bad read $name:ident with $nr:expr; $ty:ty) => (
         pub unsafe fn $name(fd: $crate::libc::c_int,
-                            data: *mut u8)
+                            data: *mut $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (bad none $name:ident with $nr:expr) => (
-        pub unsafe fn $name(fd: $crate::libc::c_int)
+    (bad write $name:ident with $nr:expr; $ty:ty) => (
+        pub unsafe fn $name(fd: $crate::libc::c_int,
+                            data: &$ty)
                             -> $crate::Result<$crate::libc::c_int> {
-            convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type))
+            convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
+        }
+        );
+    (bad readwrite $name:ident with $nr:expr; $ty:ty) => (
+        pub unsafe fn $name(fd: $crate::libc::c_int,
+                            data: *mut $ty)
+                            -> $crate::Result<$crate::libc::c_int> {
+            convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
     (none $name:ident with $ioty:expr, $nr:expr) => (

test/sys/test_ioctl.rs

@@ -1,8 +1,10 @@
 #![allow(dead_code)]
 
 // Simple tests to ensure macro generated fns compile
-ioctl!(bad do_bad with 0x1234);
-ioctl!(bad none do_bad_none with 0x1234);
+ioctl!(bad none do_bad with 0x1234);
+ioctl!(bad read do_bad_read with 0x1234; u16);
+ioctl!(bad write do_bad_write with 0x1234; u8);
+ioctl!(bad readwrite do_bad_readwrite with 0x1234; u32);
 ioctl!(none do_none with 0, 0);
 ioctl!(read read_test with 0, 0; u32);
 ioctl!(write write_test with 0, 0; u64);