Debian Codegraph @

src/sys/ioctl/mod.rs

raw
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 }