Merge #670

670: Improve ioctl docs r=asomers

Integrates suggestions and comments made in #641. Basically we hid a lot of the internal workings of things and also revised the docs to make it more clear the exact API that `nix` is exposing.

There is a small amount of code cleanup I did in the macros. I also fixed the `bad` version of the `ioctl!` macro and also added a `bad none` version for use with no-data, hardcoded-number `ioctl`s.

Would appreciate any and all feedback. Please especially fetch this code locally and generate the pretty docs for it (`cargo doc --no-deps --open`) so you can see what our users will see.

Closes #641.
Closes #573.

cc @cmr @roblabla

Author: bors[bot]

CHANGELOG.md

@@ -24,11 +24,12 @@ This project adheres to [Semantic Versioning](http://semver.org/).
   and nix::Error::UnsupportedOperation}`
   ([#614](https://github.com/nix-rust/nix/pull/614))
 - Added `cfmakeraw`, `cfsetspeed`, and `tcgetsid`. ([#527](https://github.com/nix-rust/nix/pull/527))
+- Added "bad none", "bad write_ptr", "bad write_int", and "bad readwrite" variants to the `ioctl!`
+  macro. ([#670](https://github.com/nix-rust/nix/pull/670))
 
 ### Changed
-- Changed `ioctl!(write ...)` to take argument by value instead as pointer.
-  If you need a pointer as argument, use `ioctl!(write buf ...)`.
-  ([#626](https://github.com/nix-rust/nix/pull/626))
+- Changed `ioctl!(write ...)` into `ioctl!(write_ptr ...)` and `ioctl!(write_int ..)` variants
+  to more clearly separate those use cases. ([#670](https://github.com/nix-rust/nix/pull/670))
 - Marked `sys::mman::{ mmap, munmap, madvise, munlock, msync }` as unsafe.
   ([#559](https://github.com/nix-rust/nix/pull/559))
 - Minimum supported Rust version is now 1.13.
@@ -48,13 +49,21 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Revised the termios API including additional tests and documentation and exposed it on iOS. ([#527](https://github.com/nix-rust/nix/pull/527))
 - `eventfd`, `signalfd`, and `pwritev`/`preadv` functionality is now included by default for all
   supported platforms. ([#681](https://github.com/nix-rust/nix/pull/561))
+- The `ioctl!` macro's plain variants has been replaced with "bad read" to be consistent with
+  other variants. The generated functions also have more strict types for their arguments. The
+  "*_buf" variants also now calculate total array size and take slice references for improved type
+  safety. The documentation has also been dramatically improved.
+  ([#670](https://github.com/nix-rust/nix/pull/670))
 
 ### Removed
 - Removed `io::Error` from `nix::Error` and the conversion from `nix::Error` to `Errno`
   ([#614](https://github.com/nix-rust/nix/pull/614))
 - All feature flags have been removed in favor of conditional compilation on supported platforms.
   `execvpe` is no longer supported, but this was already broken and will be added back in the next
   release. ([#681](https://github.com/nix-rust/nix/pull/561))
+- Removed `ioc_*` functions and many helper constants and macros within the `ioctl` module. These
+  should always have been private and only the `ioctl!` should be used in public code.
+  ([#670](https://github.com/nix-rust/nix/pull/670))
 
 ### Fixed
 - Fixed multiple issues compiling under different archetectures and OSes.
@@ -73,6 +82,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
   ([#623](https://github.com/nix-rust/nix/pull/623))
 - Multiple constants related to the termios API have now been properly defined for
   all supported platforms. ([#527](https://github.com/nix-rust/nix/pull/527))
+- `ioctl!` macro now supports working with non-int datatypes and properly supports all platforms.
+  ([#670](https://github.com/nix-rust/nix/pull/670))
 
 ## [0.8.1] 2017-04-16
 

src/lib.rs

@@ -31,7 +31,6 @@ pub mod libc {
     pub use self::libc::*;
 }
 
-pub use libc::{c_int, c_void};
 pub use errno::Errno;
 
 pub mod errno;
@@ -96,7 +95,7 @@ pub enum Error {
     /// The operation involved a conversion to Rust's native String type, which failed because the
     /// string did not contain all valid UTF-8.
     InvalidUtf8,
-    /// The operation is not supported by Nix, in this instance either use the libc bindings or 
+    /// The operation is not supported by Nix, in this instance either use the libc bindings or
     /// consult the module documentation to see if there is a more appropriate interface available.
     UnsupportedOperation,
 }

src/sys/aio.rs

@@ -94,7 +94,7 @@ impl<'a> AioCb<'a> {
     /// be prioritized at the process's priority level minus `prio`
     /// * `sigev_notify` Determines how you will be notified of event
     /// completion.
-    pub fn from_fd(fd: RawFd, prio: ::c_int,
+    pub fn from_fd(fd: RawFd, prio: libc::c_int,
                     sigev_notify: SigevNotify) -> AioCb<'a> {
         let mut a = AioCb::common_init(fd, prio, sigev_notify);
         a.aio_offset = 0;
@@ -118,13 +118,13 @@ impl<'a> AioCb<'a> {
     /// * `opcode` This field is only used for `lio_listio`.  It determines
     /// which operation to use for this individual aiocb
     pub fn from_mut_slice(fd: RawFd, offs: off_t, buf: &'a mut [u8],
-                          prio: ::c_int, sigev_notify: SigevNotify,
+                          prio: libc::c_int, sigev_notify: SigevNotify,
                           opcode: LioOpcode) -> AioCb<'a> {
         let mut a = AioCb::common_init(fd, prio, sigev_notify);
         a.aio_offset = offs;
         a.aio_nbytes = buf.len() as size_t;
         a.aio_buf = buf.as_ptr() as *mut c_void;
-        a.aio_lio_opcode = opcode as ::c_int;
+        a.aio_lio_opcode = opcode as libc::c_int;
 
         let aiocb = AioCb { aiocb: a, mutable: true, in_progress: false,
                             keeper: Keeper::phantom(PhantomData)};
@@ -146,13 +146,13 @@ impl<'a> AioCb<'a> {
     /// * `opcode` This field is only used for `lio_listio`.  It determines
     /// which operation to use for this individual aiocb
     pub fn from_boxed_slice(fd: RawFd, offs: off_t, buf: Rc<Box<[u8]>>,
-                          prio: ::c_int, sigev_notify: SigevNotify,
+                          prio: libc::c_int, sigev_notify: SigevNotify,
                           opcode: LioOpcode) -> AioCb<'a> {
         let mut a = AioCb::common_init(fd, prio, sigev_notify);
         a.aio_offset = offs;
         a.aio_nbytes = buf.len() as size_t;
         a.aio_buf = buf.as_ptr() as *mut c_void;
-        a.aio_lio_opcode = opcode as ::c_int;
+        a.aio_lio_opcode = opcode as libc::c_int;
 
         let aiocb = AioCb{ aiocb: a, mutable: true, in_progress: false,
                             keeper: Keeper::boxed(buf)};
@@ -173,7 +173,7 @@ impl<'a> AioCb<'a> {
     // AioCb, and they must all be the same type.  We're basically stuck with
     // using an unsafe function, since aio (as designed in C) is an unsafe API.
     pub fn from_slice(fd: RawFd, offs: off_t, buf: &'a [u8],
-                      prio: ::c_int, sigev_notify: SigevNotify,
+                      prio: libc::c_int, sigev_notify: SigevNotify,
                       opcode: LioOpcode) -> AioCb {
         let mut a = AioCb::common_init(fd, prio, sigev_notify);
         a.aio_offset = offs;
@@ -183,14 +183,14 @@ impl<'a> AioCb<'a> {
         // it.
         a.aio_buf = buf.as_ptr() as *mut c_void;
         assert!(opcode != LioOpcode::LIO_READ, "Can't read into an immutable buffer");
-        a.aio_lio_opcode = opcode as ::c_int;
+        a.aio_lio_opcode = opcode as libc::c_int;
 
         let aiocb = AioCb { aiocb: a, mutable: false, in_progress: false,
                             keeper: Keeper::none};
         aiocb
     }
 
-    fn common_init(fd: RawFd, prio: ::c_int,
+    fn common_init(fd: RawFd, prio: libc::c_int,
                    sigev_notify: SigevNotify) -> libc::aiocb {
         // Use mem::zeroed instead of explicitly zeroing each field, because the
         // number and name of reserved fields is OS-dependent.  On some OSes,
@@ -235,7 +235,7 @@ impl<'a> AioCb<'a> {
     pub fn fsync(&mut self, mode: AioFsyncMode) -> Result<()> {
         let p: *mut libc::aiocb = &mut self.aiocb;
         self.in_progress = true;
-        Errno::result(unsafe { libc::aio_fsync(mode as ::c_int, p) }).map(drop)
+        Errno::result(unsafe { libc::aio_fsync(mode as libc::c_int, p) }).map(drop)
     }
 
     /// Asynchronously reads from a file descriptor into a buffer

src/sys/event.rs

@@ -21,7 +21,7 @@ pub struct KEvent {
 #[cfg(any(target_os = "openbsd", target_os = "freebsd",
           target_os = "dragonfly", target_os = "macos",
           target_os = "ios"))]
-type type_of_udata = *mut ::c_void;
+type type_of_udata = *mut libc::c_void;
 #[cfg(any(target_os = "openbsd", target_os = "freebsd",
           target_os = "dragonfly", target_os = "macos",
           target_os = "ios"))]
@@ -127,7 +127,7 @@ libc_bitflags!(
         #[cfg(any(target_os = "macos", target_os = "ios"))]
         NOTE_EXITSTATUS,
         NOTE_EXTEND,
-        #[cfg(any(target_os = "macos", 
+        #[cfg(any(target_os = "macos",
                   target_os = "ios",
                   target_os = "freebsd",
                   target_os = "dragonfly"))]